path: root/macros/latex/contrib/xcpdftips/xcpdftips.dtx

% \iffalse      THIS IS A META-COMMENT
%<*dtx>
\ProvidesFile
%========================================================================
                            {XCPDFTIPS.DTX}
%========================================================================
%</dtx>
%% Copyright (c) 2019 Mikica Kocic
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <https://www.gnu.org/licenses/>.
%
% This is a contributed file to the LaTeX2e system.
% -------------------------------------------------
%         This is a LaTeX package to do citations with PDF tooltips.
% Installation:
%    LaTeX this file: creates docstrip installation file xcpdftips.ins
%                         AND the LaTeX documentation
%    (La)TeX xcpdftips.ins: creates package file xcpdftips.sty, and optionally
%                         the documentation driver xcpdftips.drv
%    (xcpdftips.ins and xcpdftips.drv may be edited as needed)
% Docstrip options available:
%        package - to produce a (LaTeX2e) package .sty file
%        driver  - to produce a driver file to print the documentation
%--------------------------------------------------------------------------
%
%  *** Identify the package file:-
%<package>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>
%<package>\ProvidesPackage{xcpdftips}
%<package>[2019/03/18 xcpdftips.sty v1.1 - (c) 2019 Mikica Kocic]
%<package>
%<package>\RequirePackage{bibentry}
%<package>\RequirePackage{pdfcomment}
%<package>\RequirePackage{xparse}
%<package>\RequirePackage{etoolbox}
%
%  *** Identify the driver file:-
%
%<driver>\NeedsTeXFormat{LaTeX2e}
%<driver>\ProvidesFile{xcpdftips.drv}
%
%  *** The DATE, VERSION, and other INFO
%
%\fi
%\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}
%
% \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
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \iffalse
%<*install>
%
%^^A =============================================
%^^A    Here is the docstrip installation file
%^^A    It is written on first LaTeX run if it
%^^A    does not already exist
%^^A =============================================
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{filecontents*}{xcpdftips.ins}
%
% File: xcpdftips.ins
%
% Copyright (c) 2019 Mikica Kocic
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <https://www.gnu.org/licenses/>.
%
% It is an installation file for extracting package and driver
% files from the original source file. Simply process it under
% TeX or LaTeX. It works with Docstrip versions before and after
% December 1995.

\def\batchfile{xcpdftips.ins}
\input docstrip

\preamble

=============================================
IMPORTANT NOTICE:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

This is a generated file.
It may not be distributed without the original source file \inFileName.

Full documentation can be obtained by LaTeXing that original file.
Only a few abbreviated comments remain here to describe the usage.
=============================================

\endpreamble
\postamble

<<<<< End of generated file <<<<<<

\endpostamble
\keepsilent

% Docstrip before Dec 95 does not have \generate syntax, nor
%   \declarepreamble. Must redefine them. The \generateFile called
%   for each output file individually.
% Docstrip before Dec 96 cannot interprete multiline \if..\fi
%   Thus for maximum compatibility, have only one-line conditionals

\let\oldDS F\relax
\expandafter\ifx\csname generate\endcsname\relax \let\oldDS T\relax\fi
\if\oldDS T  \def\declarepreamble#1{\preamble}\fi
\if\oldDS T  \def\declarepostamble#1{\postamble}\fi
\if\oldDS T  \generateFile{xcpdftips.sty}{f}{\from{xcpdftips.dtx}{package}} \fi

\declarepreamble\driver
============================================
This is the driver file to produce the LaTeX documentation
from the original source file \inFileName.

Make changes to it as needed. (Never change the file \inFileName!)
============================================
\endpreamble

\declarepostamble\driverq

End of documentation driver file.
\endpostamble

\ifx\oldDS T \generateFile{xcpdftips.drv}{f}{\from{xcpdftips.dtx}{driver}}\fi

\ifx\oldDS T \let\askforoverwritefalse\relax\def\generate#1{}\fi

\askforoverwritefalse
\generate{\file{xcpdftips.sty}{\from{xcpdftips.dtx}{package}}
          \file{xcpdftips.drv}{\usepreamble\driver\usepostamble\driverq
                           \from{xcpdftips.dtx}{driver}}
         }

\obeyspaces
\Msg{********************************************}%
\Msg{* For documentation, process xcpdftips.dtx *}%
\Msg{*    or the driver file      xcpdftips.drv *}%
\Msg{********************************************}
\end{filecontents*}
%</install>
%<*driver>
\documentclass[a4paper]{ltxdoc}
%<driver>%\documentclass[twoside]{ltxdoc}
%<driver>%\documentclass[a4paper]{ltxdoc}
%<driver>%\documentclass[twoside,a4paper]{ltxdoc}
\raggedbottom

 %** To include the detailed explanation of the coding, comment out
 %**   the next line
% \OnlyDescription

 %** To produce a command index: add the following line for one run,
 %**   then run  makeindex -s gind.ist xcpdftips
 %**   and reprocess, with or without this line (much faster without)
%<driver>% \EnableCrossrefs\CodelineIndex

 %** To produce a change history: add the following line for one run,
 %**   then run  makeindex -s gglo.ist -o xcpdftips.gls xcpdftips.glo
 %**   and reprocess, with or without this line (faster without)
%<driver>% \RecordChanges

\DisableCrossrefs %May stay; zapped by \EnableCrossrefs
\CodelineNumbered %May stay

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
   \DocInput{xcpdftips.dtx}
\end{document}
%</driver>
%\fi
%
% \DoNotIndex{\begin,\CodelineIndex,\CodelineNumbered,\def,\DisableCrossrefs}
% \DoNotIndex{\DocInput,\documentclass,\EnableCrossrefs,\end,\GetFileInfo}
% \DoNotIndex{\NeedsTeXFormat,\OnlyDescription,\RecordChanges,\usepackage}
% \DoNotIndex{\ProvidesClass,\ProvidesPackage,\ProvidesFile,\RequirePackage}
% \DoNotIndex{\filename,\fileversion,\filedate,\let}
% \DoNotIndex{\@listctr,\@nameuse,\csname,\else,\endcsname,\expandafter}
% \DoNotIndex{\gdef,\global,\if,\item,\newcommand,\nobibliography}
% \DoNotIndex{\par,\providecommand,\relax,\renewcommand,\renewenvironment}
% \DoNotIndex{\stepcounter,\usecounter,\nocite,\fi}
% \DoNotIndex{\@fileswfalse,\@gobble,\@ifstar,\@unexpandable@protect}
% \DoNotIndex{\AtBeginDocument,\AtEndDocument,\begingroup,\endgroup}
% \DoNotIndex{\frenchspacing,\MessageBreak,\newif,\PackageWarningNoLine}
% \DoNotIndex{\protect,\string,\xdef,\ifx,\texttt,\@biblabel,\bibitem}
%
% \setcounter{IndexColumns}{2}
% \setlength{\IndexMin}{10cm}
% \setcounter{StandardModuleDepth}{1}
%
% \GetFileInfo{xcpdftips}
%
% \title{\bfseries Citations with PDF tooltips}
%
% \author{Mikica Kocic}
%
% \date{\normalsize This paper describes package \texttt{\filename}\\[0.5ex]
%       version \fileversion{} from \filedate
% }
%
% \maketitle
%
% \pagestyle{myheadings}
% \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)
% \makeatletter \@mparswitchfalse \makeatother
%
%\iffalse
%<*package>
%
% PDF tooltips from natbib citations
%
%-----------------------------------------------------------
% See documentation in the source .dtx file for more details.
%</package>
%\fi
%
% \section{Introduction}
%
% This package allows one to be able to do \texttt{natbib} citations
% with PDF tooltips.
%
% \section{Invoking the Package}
%
% The macros in this package are included in the main document
% with the |\usepackage| command of \LaTeXe,
% \begin{quote}
% |\documentclass[..]{...}|\\
% |\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}
%
% \newcommand\btx{\textsc{Bib}\TeX}
%
% This package must be used with \btx{} and \texttt{natbib}, not with a 
% hand-written \texttt{thebibliography} environment.
% More precisely, there must be a \texttt{.bbl} file external to the \LaTeX\
% file; whether this is written by hand or by \btx\ is unimportant.
% \vspace{2ex}
%
% \DescribeMacro{\xpdfcite}
% \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,
%
% \begin{quote}
%      |\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 |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}
%
% \section{Options with \texttt{docstrip}}
%
% 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
%     comments removed;
%
% \item[\ttfamily driver] to produce a driver \texttt{.drv} file that will
%     print out the documentation under \LaTeXe. The documentation cannot
%     be printed under \LaTeX~2.09.
%
% \end{description}
%
% The source file \texttt{\filename.dtx} is itself a driver file and can
% be processed directly by \LaTeXe.
%
% \section{The Coding}
%
% This section presents and explains the actual coding of the macros.
% It is nested between |%<*package>| and |%</package>|, which
% are indicators to \texttt{docstrip} that this coding belongs to the package
% file.
%
% \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}
%
% Command for creating a tooltip box on the OCG layer. 
% The arguments are the same as for |\fcolorbox|.
%
%    \begin{macrocode}
\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

\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\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
%    \end{macrocode}
% \end{macro}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{macro}{\xcsetauthor}
%
% Set the author used for pdf comments (default: {}).
%
%    \begin{macrocode}
\gdef\XCP@opt@author{{}}
\newcommand{\xcsetauthor}[1]{\gdef\XCP@opt@author{#1}}
%    \end{macrocode}
% \end{macro}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{macro}{\xcsetmarkup}
%
% Set the markup used for pdf comments (default: Underline).
%
%    \begin{macrocode}
\gdef\XCP@opt@markup{Underline}
\newcommand{\xcsetmarkup}[1]{\gdef\XCP@opt@markup{#1}}
%    \end{macrocode}
% \end{macro}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{macro}{\xcsetcolor}
%
% 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\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 |\citep| + |\pdftooltip|.
% It has the same syntax as |\citep|.
%
%    \begin{macrocode}
\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