xcpdftips (18mar19)

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

2 files changed, 476 insertions, 64 deletions

diff --git a/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.drv b/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.drv
index f8fb591b4d4..86ea184cf64 100644
--- a/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.drv
+++ b/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.drv
@@ -36,9 +36,208 @@
 \DisableCrossrefs %May stay; zapped by \EnableCrossrefs
 \CodelineNumbered %May stay
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \begin{document}
    \DocInput{xcpdftips.dtx}
 \end{document}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newif\ifXCP@redefcite\XCP@redefcitefalse
+\newif\ifXCP@useocg\XCP@useocgfalse
+\newif\ifXCP@usetcolorbox\XCP@usetcolorboxfalse
+
+\DeclareOption{redefcite}{\XCP@redefcitetrue}
+\DeclareOption{ocg}{\XCP@useocgtrue}
+\DeclareOption{tcolorbox}{\XCP@usetcolorboxtrue}
+
+\ProcessOptions\relax
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\ifXCP@useocg
+ \ifXCP@usetcolorbox
+  \ifx\tcolorbox\undefined
+    \RequirePackage{tcolorbox}
+  \fi
+  \newcommand{\XCP@tooltipbox}[3]{%
+    \begin{tcolorbox}[colframe=#1, colback=#2,%
+        width=1.02\columnwidth, arc=2pt,%
+        boxsep=2pt, top=0ex, bottom=0ex, left=0.1em, right=0.1em%
+      ]\normalfont\small #3\end{tcolorbox}%
+  }
+ \else
+  \newcommand{\XCP@tooltipbox}[3]{%
+    \fcolorbox{#1}{#2}%
+      {\parbox[t]{\columnwidth}{\normalfont\small #3}}%
+  }
+ \fi
+\fi
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\ifXCP@useocg
+
+\RequirePackage{pdfbase,ocgbase}
+
+\RequirePackage{expl3}
+\RequirePackage{calc,linegoal}
+\RequirePackage{xcolor}
+
+
+\ExplSyntaxOn
+
+\msg_set:nnnn{xcpdftips}{support~outdated}{
+  Support~package~`#1'~too~old.
+}{
+  Get~an~up~to~date~version~of~`#1'.\\Aborting.
+}
+\@ifpackagelater{pdfbase}{2018/04/06}{}{
+  \msg_error:nnn{xcpdftips}{support~outdated}{pdfbase.sty}
+  \tex_endinput:D
+}
+\@ifpackagelater{ocgbase}{2018/04/06}{}{
+  \msg_error:nnn{xcpdftips}{support~outdated}{ocgbase.sty}
+  \tex_endinput:D
+}
+
+\let\XCP@pdfLink\pbs_pdflink:nn  % Alias for the pdflink from pdfbase
+
+\ExplSyntaxOff
+
+
+\ifx\Hy@setpdfborder\undefined\else
+  \let\Hy@setpdfborderOrig\Hy@setpdfborder
+  \def\Hy@setpdfborder{\ocgbase@insert@oc\Hy@setpdfborderOrig}%
+\fi
+
+\newsavebox{\XCP@tipText} % Temporary savebox
+\newlength{\XCP@hOffset} \setlength\XCP@hOffset{-0.1em}
+\newlength{\XCP@vOffset} \setlength\XCP@vOffset{0.2ex}
+\newlength{\XCP@lineGoal}
+
+\NewDocumentCommand{\XCP@ocgtooltip}{%
+  m % link text
+  O{yellow!5} % tooltip box color
+  m % tooltip text
+}{{%
+  \leavevmode%
+  % Create a new PDF layer
+  \ocgbase@new@ocg{ref [\XCP@keys]}{%
+    /Print<</PrintState/OFF>> %
+    /Export<</ExportState/OFF>> %
+    /View<</ViewState/OFF>> %
+  }{invisible}%
+  \edef\XCP@currentOcg{\ocgbase@last@ocg}%
+  % Insert the PDF layer into the order hierarchy (shown in the 'Layers' tab)
+  \ocgbase@tree@node@begin%
+  \XCP@currentOcg%
+  \ocgbase@tree@node@end%
+  % Disable the simultaneous visibility of multiple tooltips
+  \ocgbase@add@ocg@to@radiobtn@grp{tool@tips}{\ocgbase@last@ocg}%
+  % Emit the <link text> using \pbs_pdflink:nn
+  \XCP@pdfLink{%
+    /Subtype/Link/Border[0 0 0]/A %
+      <</S/SetOCGState/State [/Toggle \XCP@currentOcg]>> %
+  }{#1}%
+  % Create a savebox for the <tooltip text> on the PDF layer
+  \sbox\XCP@tipText{%
+    \ocgbase@oc@bdc{\XCP@currentOcg}%
+    \ocgbase@open@stack@push{\XCP@currentOcg}%
+      \XCP@tooltipbox{black!50}{#2}{#3}%
+    \ocgbase@oc@emc%
+    \ocgbase@open@stack@pop%
+    \null%
+  }%
+  % Emit the savebox (at this point we have dimensions to calc the offset)
+  \raisebox{%
+    \heightof{#1} + \the\dp\XCP@tipText + \XCP@vOffset%
+  }[0pt][0pt]{%
+    \makebox[0pt][l]{\relax%
+      \setlength\XCP@lineGoal{\linegoal}%
+      \hspace{\dimexpr\XCP@lineGoal - \linewidth + \XCP@hOffset \relax}%
+      \usebox{\XCP@tipText}%
+    }%
+  }%
+}}
+
+\fi%XCP@useocg
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newsavebox{\XCP@keynum} % Temp box for getting citation numbers using \citenum
+
+\ExplSyntaxOn
+
+\NewDocumentCommand{ \XCP@enumeratetips }%
+{ > { \SplitList , } m }%
+{%
+  \global\undef\XCP@tips%
+  \global\undef\XCP@keys%
+  \tl_map_inline:nn {#1}%
+  {%
+    \ifx\XCP@tips\undefined%
+      \global\def\XCP@keys{}%
+      \sbox\XCP@keynum{\citenum{##1}}%
+      \expandafter\xdef\csname XCP@k@##1\endcsname{\NAT@num}%
+      \xappto{\XCP@keys}{\NAT@num}%
+      \global\def\XCP@tips{}%
+      \gappto{\XCP@tips}{[\textbf{\@nameuse{XCP@k@##1}}]\ %
+        {\@nameuse{BR@r@##1\@extra@b@citeb}}}%
+    \else%
+      \sbox\XCP@keynum{\citenum{##1}}%
+      \expandafter\xdef\csname XCP@k@##1\@extra@b@citeb\endcsname{\NAT@num}%
+      \xappto{\XCP@keys}{,\NAT@num}%
+      \gappto{\XCP@tips}{,\textCR[\textbf{\@nameuse{XCP@k@##1}}]\ %
+        {\@nameuse{BR@r@##1\@extra@b@citeb}}}%
+    \fi%
+  }%
+}
+
+\ExplSyntaxOff
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\gdef\XCP@opt@author{{}}
+\newcommand{\xcsetauthor}[1]{\gdef\XCP@opt@author{#1}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\gdef\XCP@opt@markup{Underline}
+\newcommand{\xcsetmarkup}[1]{\gdef\XCP@opt@markup{#1}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\gdef\XCP@opt@color{1 1 0}
+\newcommand{\xcsetcolor}[1]{\gdef\XCP@opt@color{#1}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\gdef\XCP@opt@opacity{0}
+\newcommand{\xcsetopacity}[1]{\gdef\XCP@opt@opacity{#1}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newcommand\XCP@citetp{\@ifnextchar[{\XCP@@citetp}{\XCP@@citetp[]}}
+
+\newcommand\XCP@@citetp{}
+\def\XCP@@citetp[#1]{\@ifnextchar[{\XCP@citex[#1]}{\XCP@citex[][#1]}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newcommand\XCP@citex{}
+\gdef\XCP@citex[#1][#2]#3%
+  {%{\protect\NoHyper%
+    \ifXCP@useocg%
+      \let\textCR\par%
+      \XCP@enumeratetips{#3}%
+      \XCP@ocgtooltip%
+        {{{\protect\NoHyper\XCP@oldcite[#1][#2]{#3}\protect\endNoHyper}}}%
+        {\XCP@tips}%
+    \else%
+      \XCP@enumeratetips{#3}%
+      \pdftooltip{\XCP@oldcite[#1][#2]{#3}}{\XCP@tips}%
+      \pdfmarkupcomment[%
+        author=\XCP@opt@author,%
+        markup=\XCP@opt@markup,%
+        color=\XCP@opt@color,%
+        opacity=\XCP@opt@opacity,%
+      ]{\vphantom{.}}{\XCP@tips}%
+    \fi%
+  }%\protect\endNoHyper}}
+
+\let\XCP@oldcite\citep  % Save \citep (in the case if it becomes redefined)
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\let\xpdfcite\XCP@citetp
+\robustify{\xpdfcite}
+
+\AtBeginDocument{\nobibliography*} % Necessary to get bibentries.
+
+\ifXCP@redefcite % Override \cite
+  \let\cite\xpdfcite
+  \robustify{\cite} % Required for, e.g., captions
+\fi
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% 
 %% End of documentation driver file.
 %%
diff --git a/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.dtx b/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.dtx
index 71a8f56f6b3..ead1422810d 100644
--- a/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.dtx
+++ b/Master/texmf-dist/source/latex/xcpdftips/xcpdftips.dtx
@@ -39,7 +39,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}
 %<package>
 %<package>\ProvidesPackage{xcpdftips}
-%<package>[2019/03/10 xcpdftips.sty v1.0 - Copyright 2019 by Mikica Kocic]
+%<package>[2019/03/18 xcpdftips.sty v1.1 - (c) 2019 Mikica Kocic]
 %<package>
 %<package>\RequirePackage{bibentry}
 %<package>\RequirePackage{pdfcomment}
@@ -54,10 +54,12 @@
 %  *** The DATE, VERSION, and other INFO
 %
 %\fi
-%\ProvidesFile{xcpdftips}[2019/03/10 1.0 (PWD)]
+%\ProvidesFile{xcpdftips}[2019/03/18 1.1 (MK)]
 % \changes{1.0}{2019 Mar 10}{Initial version}
+% \changes{1.1}{2019 Mar 18}{Added support for PDF OCG}
+%
+% \CheckSum{282}
 %
-% \CheckSum{55}
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
 %   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
@@ -83,6 +85,7 @@
 %^^A    does not already exist
 %^^A =============================================
 %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \begin{filecontents*}{xcpdftips.ins}
 %
 % File: xcpdftips.ins
@@ -210,6 +213,7 @@ End of documentation driver file.
 \DisableCrossrefs %May stay; zapped by \EnableCrossrefs
 \CodelineNumbered %May stay
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \begin{document}
    \DocInput{xcpdftips.dtx}
 \end{document}
@@ -240,14 +244,14 @@ End of documentation driver file.
 %
 % \author{Mikica Kocic}
 %
-% \date{This paper describes package \texttt{\filename}\\
+% \date{\normalsize This paper describes package \texttt{\filename}\\[0.5ex]
 %       version \fileversion{} from \filedate
-%  }
+% }
 %
 % \maketitle
 %
 % \pagestyle{myheadings}
-% \markboth{M. Kocic}{PDF tooltips from natbib citations}
+% \markboth{M. Kocic}{PDF tooltips for natbib citations}
 %
 %^^A In order to keep all marginal notes on the one (left) side:
 %^^A (otherwise they switch sides disasterously with twoside option)
@@ -274,8 +278,16 @@ End of documentation driver file.
 % with the |\usepackage| command of \LaTeXe,
 % \begin{quote}
 % |\documentclass[..]{...}|\\
-% |\usepackage{|\texttt{\filename}|}|
+% |\usepackage|\oarg{options}|{|\texttt{\filename}|}|
 % \end{quote}
+% where \oarg{options} is one of: |redefcite|, |ocg|, or |tcolorbox|.
+%
+% The option |redefcite| replaces |natbib|'s |\cite| with |\xcpdfcite|.
+%
+% The option |ocg| puts tooltips on PDF layers using OCG.
+%
+% If |ocg| is used and |tcolorbox| is enabled, the package will use 
+% |\tcolorbox| instead of |\fcolorbox|.
 %
 % \section{Usage}
 %
@@ -288,30 +300,26 @@ End of documentation driver file.
 % \vspace{2ex}
 %
 % \DescribeMacro{\xpdfcite}
-% This is a replacement for \texttt{natbib}'s |\cite| macro. 
-% Usage is the same:
-%
-% \begin{quote}
-%      |\xpdfcite|\marg{key(s)}
-% \end{quote}
+% \noindent A replacement for \texttt{natbib}'s |\cite| macro.\\~
 %
 % \noindent Similarly to |\cite|, the command |\xpdfcite| may take one or two
-% optional arguments to add some text before and after the citation.
-% \vspace{2ex}
-%
-% \noindent It is also possible to replace |\cite|:
+% optional arguments to add some text before and after the citation,
 %
 % \begin{quote}
-%      |\usepackage{xcpdftips}| \\
-%      |\let\cite\xpdfcite|
+%      |\xpdfcite|\marg{key(s)}\\[0.2ex]
+%      |\xpdfcite|\oarg{post}\marg{key(s)}\\[0.2ex]
+%      |\xpdfcite|\oarg{pre}\oarg{post}\marg{key(s)}
 % \end{quote}
 %
 % \section{Caveats}
 %
-% The \texttt{\filename} package will work with \texttt{natbib} with its
-% native |\bibitem| format, and with standard \LaTeX. Nothing else can be
-% guaranteed.
-% It will also work with \texttt{url} package. 
+% The \texttt{\filename} package will work with |natbib| with its
+% native |\bibitem| format, and with standard \LaTeX.  
+% It will also work with |url| package. 
+%
+% The OCG support requires |ocgbase| and |pdfbase| versions $\ge$ 2018/04/06
+%
+% Nothing else can be guaranteed.
 %
 % \StopEventually{\PrintIndex\PrintChanges}
 %
@@ -320,6 +328,7 @@ End of documentation driver file.
 % The source \texttt{.dtx} file is meant to be processed with
 % \texttt{docstrip}, for which a number of options are available:
 %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % \begin{description}
 %
 % \item[\ttfamily package] to produce a \texttt{.sty} package file with most
@@ -341,94 +350,298 @@ End of documentation driver file.
 % are indicators to \texttt{docstrip} that this coding belongs to the package
 % file.
 %
-% \begin{macro}{\XC@enumeratetips}
+% \begin{macro}{Package options}
+% 
+% |redefcite|, |ocg|, |tcolorbox|
+%
+%    \begin{macrocode}
+\newif\ifXCP@redefcite\XCP@redefcitefalse
+\newif\ifXCP@useocg\XCP@useocgfalse
+\newif\ifXCP@usetcolorbox\XCP@usetcolorboxfalse
+
+\DeclareOption{redefcite}{\XCP@redefcitetrue}
+\DeclareOption{ocg}{\XCP@useocgtrue}
+\DeclareOption{tcolorbox}{\XCP@usetcolorboxtrue}
+
+\ProcessOptions\relax
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\XCP@tooltipbox}
 %
-% The macro |\XC@enumeratetips| gets \texttt{bibentry} for each key from 
-% the list of citations. The output is stored into |\XC@tips|, which can
-% be directly used as a tooltip text in |\pdftooltip|.
+% Command for creating a tooltip box on the OCG layer. 
+% The arguments are the same as for |\fcolorbox|.
 %
 %    \begin{macrocode}
-%<*package>
+\ifXCP@useocg
+ \ifXCP@usetcolorbox
+  \ifx\tcolorbox\undefined
+    \RequirePackage{tcolorbox}
+  \fi
+  \newcommand{\XCP@tooltipbox}[3]{%
+    \begin{tcolorbox}[colframe=#1, colback=#2,%
+        width=1.02\columnwidth, arc=2pt,%
+        boxsep=2pt, top=0ex, bottom=0ex, left=0.1em, right=0.1em%
+      ]\normalfont\small #3\end{tcolorbox}%
+  }
+ \else
+  \newcommand{\XCP@tooltipbox}[3]{%
+    \fcolorbox{#1}{#2}%
+      {\parbox[t]{\columnwidth}{\normalfont\small #3}}%
+  }
+ \fi
+\fi
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\XCP@ocgtooltip}
+%
+% Usage: |\XCP@ocgtooltip|\marg{link text}\oarg{tooltip box color}\marg{tooltip text}
+%
+% \noindent Warning: Requires |pdfbase| and |ocgbase| $>=$ 2018/04/06
+%
+%    \begin{macrocode}
+\ifXCP@useocg
+
+\RequirePackage{pdfbase,ocgbase}
+  
+\RequirePackage{expl3}
+\RequirePackage{calc,linegoal}
+\RequirePackage{xcolor}
+  
+% Check the required versions of pdfbase and ocgbase
 
 \ExplSyntaxOn
 
-\NewDocumentCommand{ \XC@enumeratetips }%
+\msg_set:nnnn{xcpdftips}{support~outdated}{
+  Support~package~`#1'~too~old.
+}{
+  Get~an~up~to~date~version~of~`#1'.\\Aborting.
+}
+\@ifpackagelater{pdfbase}{2018/04/06}{}{
+  \msg_error:nnn{xcpdftips}{support~outdated}{pdfbase.sty}
+  \tex_endinput:D
+}
+\@ifpackagelater{ocgbase}{2018/04/06}{}{
+  \msg_error:nnn{xcpdftips}{support~outdated}{ocgbase.sty}
+  \tex_endinput:D
+}
+
+\let\XCP@pdfLink\pbs_pdflink:nn  % Alias for the pdflink from pdfbase
+
+\ExplSyntaxOff
+
+% Patch hyperref (make the PDF annotations OCG-aware)
+
+\ifx\Hy@setpdfborder\undefined\else
+  \let\Hy@setpdfborderOrig\Hy@setpdfborder
+  \def\Hy@setpdfborder{\ocgbase@insert@oc\Hy@setpdfborderOrig}%
+\fi
+
+\newsavebox{\XCP@tipText} % Temporary savebox
+\newlength{\XCP@hOffset} \setlength\XCP@hOffset{-0.1em}
+\newlength{\XCP@vOffset} \setlength\XCP@vOffset{0.2ex}
+\newlength{\XCP@lineGoal}
+
+\NewDocumentCommand{\XCP@ocgtooltip}{%
+  m % link text
+  O{yellow!5} % tooltip box color
+  m % tooltip text
+}{{%
+  \leavevmode%
+  % Create a new PDF layer
+  \ocgbase@new@ocg{ref [\XCP@keys]}{%
+    /Print<</PrintState/OFF>> %
+    /Export<</ExportState/OFF>> %
+    /View<</ViewState/OFF>> %
+  }{invisible}%
+  \edef\XCP@currentOcg{\ocgbase@last@ocg}%
+  % Insert the PDF layer into the order hierarchy (shown in the 'Layers' tab)
+  \ocgbase@tree@node@begin%
+  \XCP@currentOcg%
+  \ocgbase@tree@node@end%
+  % Disable the simultaneous visibility of multiple tooltips
+  \ocgbase@add@ocg@to@radiobtn@grp{tool@tips}{\ocgbase@last@ocg}%
+  % Emit the <link text> using \pbs_pdflink:nn
+  \XCP@pdfLink{%
+    /Subtype/Link/Border[0 0 0]/A %
+      <</S/SetOCGState/State [/Toggle \XCP@currentOcg]>> %
+  }{#1}%
+  % Create a savebox for the <tooltip text> on the PDF layer
+  \sbox\XCP@tipText{%
+    \ocgbase@oc@bdc{\XCP@currentOcg}%
+    \ocgbase@open@stack@push{\XCP@currentOcg}%
+      \XCP@tooltipbox{black!50}{#2}{#3}%
+    \ocgbase@oc@emc%
+    \ocgbase@open@stack@pop%
+    \null%
+  }%
+  % Emit the savebox (at this point we have dimensions to calc the offset)
+  \raisebox{%
+    \heightof{#1} + \the\dp\XCP@tipText + \XCP@vOffset%
+  }[0pt][0pt]{%
+    \makebox[0pt][l]{\relax%
+      \setlength\XCP@lineGoal{\linegoal}%
+      \hspace{\dimexpr\XCP@lineGoal - \linewidth + \XCP@hOffset \relax}%
+      \usebox{\XCP@tipText}%
+    }%
+  }%
+}}
+  
+\fi%XCP@useocg
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\XCP@enumeratetips}
+%
+% Gets \texttt{bibentry} for each key from the list of citations. 
+% The output is stored into |\XCP@tips|, which can be directly used as 
+% a tooltip text in |\pdftooltip|.
+%
+%    \begin{macrocode}
+\newsavebox{\XCP@keynum} % Temp box for getting citation numbers using \citenum
+
+\ExplSyntaxOn
+
+\NewDocumentCommand{ \XCP@enumeratetips }%
 { > { \SplitList , } m }%
 {%
-  \global\undef\XC@tips%
-  \tl_map_inline:nn {#1}% 
+  \global\undef\XCP@tips%
+  \global\undef\XCP@keys%
+  \tl_map_inline:nn {#1}%
   {%
-    \ifx\XC@tips\undefined%
-      \global\def\XC@tips{}%
-      \gappto{\XC@tips}{--~~\@nameuse{BR@r@##1\@extra@b@citeb}}%
+    \ifx\XCP@tips\undefined%
+      \global\def\XCP@keys{}%
+      \sbox\XCP@keynum{\citenum{##1}}%
+      \expandafter\xdef\csname XCP@k@##1\endcsname{\NAT@num}%
+      \xappto{\XCP@keys}{\NAT@num}%
+      \global\def\XCP@tips{}%
+      \gappto{\XCP@tips}{[\textbf{\@nameuse{XCP@k@##1}}]\ %
+        {\@nameuse{BR@r@##1\@extra@b@citeb}}}%
     \else%
-      \gappto{\XC@tips}{,\textCR--~~\@nameuse{BR@r@##1\@extra@b@citeb}}%
+      \sbox\XCP@keynum{\citenum{##1}}%
+      \expandafter\xdef\csname XCP@k@##1\@extra@b@citeb\endcsname{\NAT@num}%
+      \xappto{\XCP@keys}{,\NAT@num}%
+      \gappto{\XCP@tips}{,\textCR[\textbf{\@nameuse{XCP@k@##1}}]\ %
+        {\@nameuse{BR@r@##1\@extra@b@citeb}}}%
     \fi%
   }%
 }
 
 \ExplSyntaxOff
-
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\XC@citetp}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\xcsetauthor}
 %
-% This macro is in fact |\xpdfcite|. \\
-% It is a wrapper for |\XC@@citetp| to handle variable number of arguments.
+% Set the author used for pdf comments (default: {}).
 %
 %    \begin{macrocode}
-
-\newcommand\XC@citetp{\@ifnextchar[{\XC@@citetp}{\XC@@citetp[]}}
-
+\gdef\XCP@opt@author{{}}
+\newcommand{\xcsetauthor}[1]{\gdef\XCP@opt@author{#1}}
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\XC@@citetp}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\xcsetmarkup}
 %
-% This macro is called from |\xpdfcite|. \\
-% It is a wrapper for |\XC@citex| to handle variable number of arguments.
+% Set the markup used for pdf comments (default: Underline).
 %
 %    \begin{macrocode}
-
-\newcommand\XC@@citetp{}
-
-\def\XC@@citetp[#1]{\@ifnextchar[{\XC@citex[#1]}{\XC@citex[][#1]}}
-
+\gdef\XCP@opt@markup{Underline}
+\newcommand{\xcsetmarkup}[1]{\gdef\XCP@opt@markup{#1}}
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\XC@citex}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\xcsetcolor}
 %
-% This macro does the actual job.
-% It is an internal wrapper for the combined |\pdftooltip| and |\citep|. 
+% Set the color used for pdf comments (default: yellow).
 %
 %    \begin{macrocode}
+\gdef\XCP@opt@color{1 1 0}
+\newcommand{\xcsetcolor}[1]{\gdef\XCP@opt@color{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\xcsetopacity}
+%
+% Set the opacity used for pdf comments (default: 0).
+%
+%    \begin{macrocode}
+\gdef\XCP@opt@opacity{0}
+\newcommand{\xcsetopacity}[1]{\gdef\XCP@opt@opacity{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\XCP@citetp}
+%
+% This macro is in fact |\xpdfcite|. \\
+% It is a wrapper for |\XCP@@citetp| to handle variable number of arguments.
+%
+%    \begin{macrocode}
+\newcommand\XCP@citetp{\@ifnextchar[{\XCP@@citetp}{\XCP@@citetp[]}}
 
-\newcommand\XC@citex{}
-
-\def\XC@citex[#1][#2]#3{%
-  \XC@enumeratetips{#3}%
-  \pdftooltip{\XC@oldcite[#1][#2]{#3}}{\XC@tips}%
-}
-
-\let\XC@oldcite\citep  % Save \citep (in the case if it becomes redefined)
+\newcommand\XCP@@citetp{}
+\def\XCP@@citetp[#1]{\@ifnextchar[{\XCP@citex[#1]}{\XCP@citex[][#1]}}
+%    \end{macrocode}
+% \end{macro}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \begin{macro}{\XCP@citex}
+%
+% An internal macro that does the actual job for |\xpdfcite|.
+%
+%    \begin{macrocode}
+\newcommand\XCP@citex{}
+\gdef\XCP@citex[#1][#2]#3%
+  {%{\protect\NoHyper%
+    \ifXCP@useocg%
+      \let\textCR\par%
+      \XCP@enumeratetips{#3}%
+      \XCP@ocgtooltip%
+        {{{\protect\NoHyper\XCP@oldcite[#1][#2]{#3}\protect\endNoHyper}}}%
+        {\XCP@tips}%
+    \else%
+      \XCP@enumeratetips{#3}%
+      \pdftooltip{\XCP@oldcite[#1][#2]{#3}}{\XCP@tips}%
+      \pdfmarkupcomment[%
+        author=\XCP@opt@author,%
+        markup=\XCP@opt@markup,%
+        color=\XCP@opt@color,%
+        opacity=\XCP@opt@opacity,%
+      ]{\vphantom{.}}{\XCP@tips}%
+    \fi%
+  }%\protect\endNoHyper}}
 
+\let\XCP@oldcite\citep  % Save \citep (in the case if it becomes redefined)
 %    \end{macrocode}
 % \end{macro}
 %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % \begin{macro}{\xpdfcite}
 %
-% A wrapper for the combined |\pdftooltip| and |\citep|.\\
+% A wrapper for |\citep| + |\pdftooltip|.
 % It has the same syntax as |\citep|.
 %
 %    \begin{macrocode}
-
-\let\xpdfcite\XC@citetp
+\let\xpdfcite\XCP@citetp
+\robustify{\xpdfcite}
 
 \AtBeginDocument{\nobibliography*} % Necessary to get bibentries.
 
+\ifXCP@redefcite % Override \cite
+  \let\cite\xpdfcite  
+  \robustify{\cite} % Required for, e.g., captions
+\fi
 %    \end{macrocode}
 % \end{macro}
 %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % \Finale