fancytooltips 1.12 (3jun12)

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

1 files changed, 451 insertions, 152 deletions

diff --git a/Master/texmf-dist/source/latex/fancytooltips/fancytooltips.dtx b/Master/texmf-dist/source/latex/fancytooltips/fancytooltips.dtx
index b8234789e25..5685590a472 100644
--- a/Master/texmf-dist/source/latex/fancytooltips/fancytooltips.dtx
+++ b/Master/texmf-dist/source/latex/fancytooltips/fancytooltips.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2004-2010 by Robert Marik <marik@mendelu.cz>
+% Copyright (C) 2004-2012 by Robert Marik <marik@mendelu.cz>
 % ----------------------------------------------------------
 % 
 % This file may be distributed and/or modified under the
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{fancytooltips}
 %<*package>
-    [2010/06/10 v1.8 fancytooltips.dtx  file]
+    [2012/06/12 v1.12 fancytooltips.dtx  file]
 %</package>
 %
 %<*driver>
@@ -30,35 +30,31 @@
 \EnableCrossrefs         
 \CodelineIndex
 \RecordChanges
-\usepackage[pdftex]{color}
-\usepackage[filename=tip,mouseover,movetips]{fancytooltips}
+\OnlyDescription
+\usepackage{xcolor,graphicx,listings}
+\usepackage[filename=tip,mouseover,movetips,fg]{fancytooltips}
 \buttontipwidth=2cm
 \buttontipheight=2cm
 \begin{document}
 \color{black}
   \DocInput{fancytooltips.dtx}
-  \PrintIndex
 \end{document}
 %</driver>
 % \fi
 %
-% \CheckSum{1075}
-%
-% \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         \~}
+% \CheckSum{1186}
+%
+% \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 \~}
 %
 %
 % \changes{v1.0}{2007/02/15}{Initial version}
@@ -86,7 +82,7 @@
 %
 % \changes{v1.6}{2010/04/10}{Added options \texttt{debug},
 %   \texttt{active} and \texttt{inactive}, added an example with
-%   automatical previews for equations and floats. Added handling of
+%   automatic previews for equations and floats. Added handling of
 %   this.dirty and app.focusRect. Changed the name of the file with
 %   tooltips. Added starred version of \texttt{tooltip} command.}
 %
@@ -95,12 +91,26 @@
 %
 % \changes{v1.8}{2010/06/10}{Added hook do insert stuff on each page.}
 %
+% \changes{v1.9}{2011/12/04}{Changed expansion in the new |\ref|
+% command provided by |FancyHook| macro (see |fancy-preview|
+% facility).}
+%
+% \changes{v1.10}{2012/05/09}{New script preview-latex. New options
+% |previewall| and |nosoap|.}
+%
+% \changes{v1.11}{2012/05/11}{Fixed bug related to bad position if
+% |fg| option is used and \texttt{evensidemargin} is different from
+% \texttt{oddsidemargin}.}
+%
+% \changes{v1.12}{2012/06/12}{Documentation updated. New option
+% |tooltipmark|.}
+%
 % \GetFileInfo{fancytooltips.dtx}
 %
 % \DoNotIndex{\newcommand,\newenvironment}
 % 
 %
-% \title{The \textsf{fancytooltips} package\thanks{This document
+% \title{The \textsf{fancytooltips} package, the \textsf{fancy-preview} script\thanks{This document
 %     corresponds to \textsf{fancytooltips}~\fileversion, dated
 %     \filedate.} \thanks{Supported by grants 18/2006, 99/2008 and 131/2010
 %     of Higher
@@ -109,97 +119,107 @@
 %
 % \maketitle
 %
+% \setcounter{tocdepth}{2}\tableofcontents\rightskip=0em plus 0.2em\sloppy
 % \section{Introduction}
 %
-% The package |fancytooltips| is a package for \LaTeX. The pdf can be
-% created by pdflatex or by latex + dvips +
-% AdobeDistiller\footnote{not free ps2pdf} + Adobe
-% Acrobat\footnote{not free Adobe Reader.}. It allows to create
-% tooltips in a similar way like |cooltooltips| package, but the
-% tooltip is a page from another PDF file. In this way you can use
-% mathematics, pictures and animations in your tooltips. The
-% resulting PDF file can be used also with free Abobe Reader.
-%
-% The \color{black}tooltips are activated by clicking the active area
-% on the screen and deactivated after closing page or by moving mouse
-% outside the link. You can try the links \tooltip{here}{1}
-% (Einstein's formula) and also \tooltipanim{here}{2}{7} (animation --
-% numbers from 1 to 6).  You have to use the free Adobe Reader or
-% nonfree Adobe Acrobat to see the effect (xpdf, evince and others
-% fail to work with JavaScripts). For more examples how the
-% presentation may look like see the |examples| subdirectory.
-%
-% Similar functionality can be achieved using |pdfcomment| (smaller
+% The \LaTeX{} package |fancytooltips| allows to insert tooltips into
+% PDF documents -- a popup windows appears if the mouse hovers or
+% clicks particular area. You can use plain text as well as
+% mathematics, pictures and animations in your tooltips. The PDF
+% viewer must interpret Javascripts to make the tooltips work. This is
+% currently true only for (free) Abobe Reader and (commercial) Adobe
+% Acrobat. There are two ways how to produce the PDF file. The
+% simplest way is to use |pdflatex|. Another option is |latex| +
+% |dvips| + AdobeDistiller\footnote{not free |ps2pdf|} + Adobe
+% Acrobat\footnote{not free Adobe Reader.}.
+%
+% \color{black}Here you can test two tooltips: \tooltip{Einstein's
+% formula}{1} and simple \tooltipanim{animation}{2}{7} (numbers from 1
+% to 6). For more examples how the presentation may look like see the
+% |examples| subdirectory. We also provide a Perl script
+% |fancy-preview| which allows to extract equations, theorems and
+% related parts of text into separate PDF file and insert tooltips
+% after each |\ref|, |\eqref| and |\cite| command automatically. For
+% more information see Figure \ref{fig:1} and demos (scientific
+% papers, presentations, tests) at
+% \url{http://user.mendelu.cz/marik/fancy-preview}.
+%
+% Related \LaTeX{} packages are |cooltooltips|, |pdfcomment| (smaller
 % size of the resulting PDF, but restricted to plain text), |ocgtools|
 % (works with layers, only |pdflatex| is supported) and Acro\TeX{}
 % (works with layers, only |latex| + |dvips| + Adobe Distiller + Adobe
 % Acrobat are supported). All these ``similar'' packages allow to
-% write the text for he tooltips and the text for the main document in
-% one file. In contrast to this approach, |fancytooltips| package
-% makes use of an external file. However, if you prefer to write both
-% tooltips in one file, you can preprocess your file using |preview|
-% package and extract tooltips automatically, as shown in the
-% |examples/fancy-preview| directory.
-%
-% The buttons are created using |eforms.sty| which is a part of
-% AcroTeX bundle.
-%
-% \section{Usage}
-% \subsection{How the package works}
-% We have to prepare external file with content of tooltips first.
-% The pages of this external file are inserted as icons at hidden
-% buttons into the presentation. Whenever we use a command to insert
-% tooltip, the following actions are performed
-% \begin{itemize}\item 
-%   The current page is covered by invisible transparent button which
-%   spans across the whole page (the information about the pages with
-%   tooltips is stored in |aux| file and hence we have to run \LaTeX{}
-%   \textit{three times}). The button has an associated JavaScript
-%   action to close all tooltips (i.e. make itself and other related
-%   buttons hidden).
-% \item The button is created in text. This button is transparent,
-%   covers the text typeset by \TeX{} into |\hbox| of dimension 0 pt
-%   and allows to activate a JavaScript. This JavaScript takes the
-%   picture required, puts this picture as icon to the button which
-%   covers the corresponding page and makes this button visible.
+% write the text for the tooltips inside the main document. In
+% contrast to this approach, |fancytooltips| package makes use of an
+% external file. This allow to use graphics or mathematical
+% expressions in the tooltips.
+%
+% The package requires |eforms.sty| and |insdljs.sty| packages, which
+% are part of AcroTeX bundle
+% (\url{http://www.math.uakron.edu/~dpstory/webeq.html}).
+%
+% \section{Usage of \texttt{fancytooltips.sty}}
+% \subsection{Small technical background}
+% 
+% \begin{itemize}
+% \item The pages from the external PDF file with tootlips are
+%   inserted as icons at hidden buttons into the resulting
+%   PDF. 
+% \item If you insert tooltip, the current page is covered by an
+%   invisible transparent button which spans across the whole page
+%   (the information about the pages with tooltips is stored in |aux|
+%   file and hence we have to run \LaTeX{} \textit{three times}). The
+%   button has an associated JavaScript action to close all tooltips
+%   (i.e. make itself and other related buttons hidden).
+% \item Another button which reveals tooltip is created. This button
+%   is transparent, covers the text typeset by \TeX{} and allows to
+%   activate a JavaScript. This JavaScript takes the picture required,
+%   puts this picture as icon to the button which covers the
+%   corresponding page and makes this button visible.
 % \item Each page has an associated action which closes all tooltips
 %   when the page is opened.
 % \end{itemize}
 % 
 % \subsection{The file with tooltips} 
-% The file with tooltips is an ordinary pdf file, one tooltip per
-% page, tooltips should be in the top right corner at the page, in a
-% colored box and the rest of the page should be transparent. If you
-% consider to use |movetips| option (see below), then every page
-% should have the dimensions equal to the dimensions of the colored
-% box with tooltip\footnote{Look at the files \texttt{tooltipy.tex} and
-%   \texttt{tooltipy.pdf} from |examples| subdirectory for a simple example
-%   how to meet this condition under pdf\LaTeX}. We also provide
-% simple cross referencing mechanism to reffer to the tooltips. If the
-% pdf file is created by \LaTeX, \DescribeMacro{\keytip} you can
-% define keywords to reffer to the pages using |\keytip| command.
-% Simply put |\usepackage[createtips]{fancytooltips}| into preamble
-% and write \texttt{\string\keytip}\marg{foo} in document. This writes
+% The file with tooltips is an ordinary PDF file, one tooltip per
+% page. Tooltips should be in the top right corner at the page, in a
+% \textit{box with nontransparent background} and the rest of the page
+% should be transparent. If you consider to use |movetips| option
+% which causes the tooltip appear near the mouse cursor instead of in
+% the top right corner (see below), then every page should have the
+% dimensions equal to the dimensions of the colored box with
+% tooltip\footnote{Look at the files \texttt{tooltipy.tex} and
+% \texttt{tooltipy.pdf} from |examples| subdirectory for a simple
+% example how to meet this condition under pdf\LaTeX. You may also use
+% ordinary \LaTeX{} class, set \texttt{\textbackslash pagestyle\{empty\}} and crop the boundary.}. You can
+% call the tooltips by their page numbers, but for better comfort we
+% also provide simple cross referencing mechanism. If the pdf file is
+% created by \LaTeX, \DescribeMacro{\keytip} you can define keywords
+% to refer to the pages using |\keytip| command.  Simply put
+% |\usepackage[createtips]{fancytooltips}| into preamble and write
+% \texttt{\string\keytip}\marg{foo} in document. This writes
 % information about keyword \meta{foo} and the pagenumber into file
-% |\jobname.tips|. 
+% |\jobname.tips|. See
+% \url{http://user.mendelu.cz/marik/fancytooltips} for some tooltip
+% templates.
 %
-% \subsection{The file with presentation -- pdf\LaTeX users}
-% In the file with presentation, the user is responsible
+% \subsection{The file with presentation}
+% In the file with presentation, the user is responsible to
 % \begin{itemize}
 % \item input either |color| or |xcolor| package in the
 %   preamble
 % \item \LaTeX{} the file two times (we write some macros into |aux|
-%   file).
+%   file) or three times (if option |fg| is used).
 % \end{itemize}
-% This is not comfortable for the user, but everybody uses different
-% set of packages and from this reason, this part is left to the user.
-% (And among others, the |color| or |xcolor| package is probably
-% inputted by the package which is used to build the presentation.)
+% You may use the following options to set the necessary information
+% and change the default behavior of the package.
 %
-% \begin{description}\def\iitem#1{\item[#1]}\sloppy\raggedright
-% \iitem{filename} To input the tooltips from file
-% \meta{foo.pdf} call the package with |filename| option:
-% |\usepackage[filename=foo]{fancytooltips}|.
+% \def\iitem#1{\item[{\color{blue!50!black}\texttt{#1}}]} 
+% \begin{description}\sloppy\rightskip 0 pt plus 1 em
+%   \iitem{filename} To input the tooltips from file \meta{foo.pdf}
+%   call the package with |filename| option:
+%   |\usepackage[filename=foo]{fancytooltips}|. This option is
+%   required if compiled with |pdflatex|.
 %
 % \iitem{movetips} By default, tooltip appears in the
 % top right corner of the page (use View--PageLayout-Single Page in
@@ -233,14 +253,24 @@
 %   only on the page which include tooltips, you may want to use
 %   option |fixcolor| to fix it.
 %
+%   \iitem{fixcolor} See |blur| option.
+%
 %   \iitem{debug} Prints two alerts reporting success or problems when
 %   opening PDF file in Adobe Acrobat (Adobe Reader).  Use this option
-%   to find possible source of problems. See also the section
-%   Troubleshooting \dots in this manual.  
+%   to find possible source of problems. See also the Section
+%   \ref{sec:tr} in this manual.  
 %
-%   \iitem{noextratext} Do not append any mark at the end of the link
+%   \iitem{noextratext} No mark is appended at the end of the link
 %   which opens tooltips (see help for |\tooltip|).
 %
+%   \iitem{nosoap} A single space is used to occupy the space for
+%   button produced by |\tooltip*| command instead of blue soap. As a
+%   result, the button produced by |\tooltip*| works as usual, but it
+%   is invisible. This is sometimes convenient for the user, since the
+%   mark does not disturb the text. However, the author has to
+%   instruct the user, that the hidden buttons follow links from
+%   cross references.
+%
 %   \iitem {fg} The button for displaying pictures is placed on
 %   background and the buttons which activate tooltips are placed
 %   immediately in the text by default. With |fg| option all these
@@ -251,8 +281,28 @@
 %   anything in dvi mode now (despite the fact that pdf\LaTeX\
 %   provides the feature also for dvi mode), but this could be changed
 %   if someone requests this feature. Use this option for example, if
-%   you use buttons and forms in your PDF (like tests produced by
-%   Acro\TeX) and the tooltips should be on the top when displayed.
+%   you use frame around hyperlinks or buttons and form fields in your
+%   PDF (like tests produced by Acro\TeX).
+%
+%   \iitem{preview} Redefines |\ref|, |\eqref| and |\cite| commands to
+%   work with tooltips extracted by |fancy-preview|, see Section
+%   \ref{sec:fancy-preview} and demo files in |example/fancy-preview|
+%   directory. The tooltip is inserted only if the target of the
+%   reference is on different PDF page as the tooltip. This option is
+%   suitable for presentations where the whole PDF page is
+%   visible. Replaces former |\FancyHook| command.
+%
+%   \iitem{previewall} Like |preview| but shows tooltip also if the
+%   target is on the same page. Suitable for enhanced versions of
+%   papers written on A4 page.
+%
+%   \def\aaa#1{#1\hbox
+%   {\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
+%   {fancytipmark#1.pdf}}}}} \iitem{tooltipmark} Allows to change the
+%   tooltipmark to some predefined styles, values are \aaa1, \aaa2,
+%   \aaa3 and \aaa4. Note that you can change the mark to whatever
+%   different by redefining |\TooltipExtratext| command. Work only in
+%   pdflatex mode. 
 %
 % \end{description}
 % 
@@ -267,10 +317,10 @@
 % \DescribeMacro{\TooltipExtratext} The printed text \meta{stuff} is
 % followed by |\TooltipExtratext| command. The default value is small
 % blue soap, as you have seen in the second paragraph of this
-% documentation. There is a package |noextratext| which defines
+% documentation. There is a |noextratext| option which defines
 % |\TooltipExtratext| to be empty. \DescribeMacro{noextratext option}
 % If \marg{keyword-or-pagenumber} is not recognized as valid keyword
-% for tooltips,
+% for tooltips, it is supposed to be pagenumber.
 %
 % The text \marg{stuff} is inserted in |\hbox| by
 % |\tooltip|. \DescribeMacro{\tooltip*}With starred version of the
@@ -288,27 +338,23 @@
 % |\def\delayinterval{100}|. There is also starred version which works
 % similarly like |\tooltip*| command.
 %
-% \DescribeMacro{\FancyHook} Redefines |\ref| and |\eqref| commands to
-% work with preview, see the demo files in |example/fancy-preview|
-% directory.
-%
-% \DescribeMacro{\TooltipRefmark} Extra text added to |\ref| and
-% |\eqref| commands with previews, see the demo files in
-% |example/fancy-preview| directory. The default value is the same as
-% for |\TooltipExtratext|.
+% \DescribeMacro{\TooltipRefmark} Extra text added to |\ref|, |\eqref|
+% and |\cite| commands with previews, see Section
+% \ref{sec:fancy-preview}. The default value is the same as for
+% |\TooltipExtratext|.
 %
-% \subsection{Changes for dvips users}
+% \subsubsection{Changes for dvips users}
 % Dvips users also have to prepare tooltips into PDF file, not eps as
 % usual. But we have to insert these tooltips in Adobe Acrobat Pro
 % program. If you use Acrobat Pro version 8.1 and later, install the
 % file \texttt{aeb.js} from AcroTeX eDucation bundle as described in
 % the documentation to AcroTeX.\footnote{If you do not install
-%   \texttt{aeb.js} properly, you can still create your presentation ,
-%   but you have to import fdf file manually, see the section
+%   \texttt{aeb.js} properly, you can still create your presentation,
+%   but you have to import the |fdf| file manually, see the section
 %   Troubleshooting and known problems.}
 %
 % Since \LaTeX{} is not capable to find the number of pages in
-% external PDF file with tooltips, dvips users have to specify option
+% external PDF file with tooltips, \DescribeMacro{dvips}dvips users have to specify option
 % |dvips| in |fancytooltips| package.  \DescribeMacro{pages} You have
 % to use also a |pages| option with the number of pages in the PDF
 % file with tooltips, if you use dvips route. You have to call the
@@ -331,9 +377,210 @@
 % |ImportTooltips();| fails, you either have not the PDF file with
 % tooltips in current directory, or the PDF file does not contain
 % JavaScripts. In the latter case insert document level JavaScripts
-% manually as described in the next section.
+% manually as described in the Section \ref{sec:tr}.
+%
+% \section{Tootlips at
+% references: \texttt{fancy-preview}} \label{sec:fancy-preview} 
+% \subsection{Basic usage}
+% There is a Perl script |fancy-preview| which can be used to extract
+% text from bibliography items, numbered equations, numbered theorems,
+% lemmas, etc, put this text into separate PDF file and add this text
+% as tooltips to the corresponding |\ref|, |\eqref| and |\cite|
+% commands. Reading the resulting file may look like on Figure
+% \ref{fig:1}.
+% \begin{figure}
+%   \centering
+%\fbox{\includegraphics[width=0.95\textwidth]{cite.png}}
+%   \caption{\texttt{fancy-preview}}
+%   \label{fig:1}
+% \end{figure}
+% 
+%
+% The script |fancy-preview| has been tested with Texlive2011 on both
+% Linux and MS Windows. To run this script you need working Perl
+% installation (usually present on Linux workstations, on MS Windows
+% you may need to install Perl from
+% \url{http://www.activestate.com/activeperl}) and |Config::IniFiles|
+% module\footnote{Package |libconfig-inifiles-perl| on Ubuntu Linux,
+% |cpan Config::IniFiles| or |ppm install Config::Inifiles| on MS
+% Windows. Alternatively you can run |ppm| without any parameters to
+% invoke the GUI.})
+%
+%   To compile your document |file.tex| do the following
+%   \begin{itemize}
+%   \item Put |\usepackage{hyperref}| into the preamble of your document
+%     (if not already loaded).
+%   \item If you write references in |thebibliography| environment, put
+%     empty line after each |\bibitem| command (including the last item
+%     in |thebibliography|).
+%   \item Run |fancy-preview file|. After several compilations you
+%     should get the PDF file |file.pdf|.
+%   \end{itemize}
+%   The default work-flow is the following.  The file is compiled with
+%   |pdflatex| to get correct numbers of equations and in the first
+%   pass of |preview.sty| we extract displayed equations (but the
+%   numbers are thrown away). After this we crop the PDF file by using
+%   |pdfcrop| program (an alternate program can be specified as
+%   optional parameter). Then we extract numbered environments
+%   (theorem, Theorem, lemma, corollary, definition, figure, table)
+%   using the second pass and crop the PDF file again. After this we
+%   merge all equations, theorems etc which are marked with |\label|
+%   command. The PDF file with extracted parts of the text is the used
+%   as source of toltips in final compilations.
+%
+% Many things can be customized. The following options are
+% available.
+% \begin{description}
+%   \iitem{pdfcrop} You may specify an alternative batch file to crop
+%   boundary of PDF file. Default is |pdfcrop|. The command line for
+%   an alternative program to crop PDF file is supposed to be the
+%   following: |programname input.pdf output.pdf|. Using optimal
+%   program to PDF file may be much fasater and may produce
+%   significantly smaller files. \iitem{tooltips} You may combine
+%   the tooltips extracted by |fancy-preview| with ``ordinary hand
+%   made tooltips''. Simply call |fancytooltips| in the main document
+%   by |\usepackage[inactive]{fancytooltips}| in your document and
+%   specify the file with tooltips in the command line of the
+%   |fancy-preview| or in the |ini| file. You may also compile your
+%   file by |pdflatex| and get ``normal'' PDF output (the compilation
+%   is way faster). \iitem{fancy\underline{ }options} Options passed
+%   |fancytooltips| in final compilations. Default is
+%   |previewall,nosoap|. Options |mouseover| and |movetips| are added
+%   automaticaly.\iitem{ini\underline{ }file}Specifices the |ini| file
+%   with configuration, see the next subsection.
+% \end{description}
+% \subsection{Configuration from ini files}
+% Other customization can be done via |ini| files. The script looks
+% for customizations in the file specified by |ini_file| command line
+% parameter. If this parameterer is not used, the script looks for
+% customization in two default locations: |~/.fancy-preview.ini| and
+% in |./fancy-preview.ini| (both files are used if both exist). You
+% can use |~/.fancy-preview.ini| for customizations related to all
+% your projects and |./fancy-preview.ini| for projects in the current
+% directory. The options from the file
+% |./fancy-preview.ini| override |~/.fancy-preview.ini| and the
+% options from command line override options from
+% |./fancy-preview.ini|. The format is described at
+% \url{http://search.cpan.org/~shlomif/Config-IniFiles-2.75/lib/Config/IniFiles.pm}.
+%
+% The parameters are divided into two sections, |[main]| and |[latex]|.
+% In section |[main]| of |ini| file you can set parameters |pdfcrop|,
+% |tooltips| and |fancy_options|. 
+% 
+% In the section |[latex]| if the initialization file you can
+% customize the compilation by \LaTeX. Here you can set parameters
+% |environments| and |snarfenvironments| to set the environments which
+% will be extracted. The default values are
+% |environments=Theorem,theorem,lemma,corollary,definition| and
+% |snarfenvironments=figure|.
+%
+% The material from |tex| file is extracted in three passes. These
+% passes are denoted by |a|, |b| and |c|. If
+% \texttt{\string\label}\marg{foo} appears in the text which is marked
+% for extraction, then the corresponding
+% \texttt{\string\newlabel}\marg{foo} command is written to the |aux|
+% file and \meta{foo} is supposed to be the name of the keyword
+% corresponding to the PDF page with the text.
+%
+% If a referenced material appears in more passes, then the priority
+% is set in the variable |$latex{'pass_order'}| and can be customized
+% in the ini file in |[latex]| section as |pass_order| parameter. The
+% default value is |pass_order=acb|, i.e.  |c| overrides |b| and |a|
+% overrides |c|.
+%
+% As a typical example consider equation with label |\label{eq}| in
+% numbered theorem with label |\label{th}|. The equation is extracted
+% in pass |a| (displayed equation) and in pass |b| (the whole
+% theorem). The corresponding |\newlabel{eq}| command appers in two
+% |aux| files -- from passes |a| and |b|. The first one corresponds to
+% the PDF page with equation, the latter to the PDF page with whole
+% theorem. Since |a| overrides |b|, then |\ref{eq}| and |\eqref{eq}|
+% commands show the number of the equation followed by the tooltip
+% with equation only. Further |\ref{th}| shows number of the theorem
+% followed by the tooltip with the whole theorem. If you set |pass_order=ba|, then both |\ref{eq}| and |\ref{th}| are followed by the
+% same tooltip.
+%
+% The following options are available\footnote{These
+% options are used as keywords in a hash variable \texttt{latex}, i.e. for
+% default value of \texttt{param} parameter search the file \texttt{fancy-preview}
+% for \texttt{\$latex\{'param'\}}.}.
+%\begin{itemize}
+%  \iitem {a} Defines commands for the first pass. It
+%  inserts |preview.sty| command which extracts displayed
+%  mathematics. Also resets |\tagform@| and |\@eqnnum| to skip
+%  printing of equation numbers.
+%  \iitem {a\underline{ }extra} Defines material which is appended to |a|
+%
+%  \iitem {b} Defines commands fot the second pass. In this \LaTeX{}
+%  run are (by default) floating figures and theorem-like environments
+%  extracted. Inserts |preview.sty|. At the runtime,
+%  |\PreviewEnvironment[{[]}]{env}| and
+%  |\PreviewSnarfEnvironment[{[]}]{env}| for each |env| in comma
+%  separated list from |environments| and |snafenvironments| is added,
+%  respectively.
+%  \iitem {b\underline{ }extra} Defines material which is appended to |b|
+%
+% \iitem{environments} See |b| option. 
+%
+% \iitem{snarfenvironments} See |b| option. Default value is |figure|.
+%
+% \iitem {c} If empty (default value), then the third pass is
+% skipped. Otherwise, you may activate |preview.sty| similarly like in
+% |b| (for a template see the source code and the default setting of
+% |$latex{'b'}|) and extract environments and commands according to
+% your interest. A possible application is to extract |minipage|
+% environments, if there are two or more figures inserted in
+% |minipage| environments into one |figure| environment.
+%
+% \iitem{pass\underline{ }order} Sets priority, which pass is supposed
+% to produce the output for a |\label| which is extracted more times
+% than once, see the previous paragraphs for explanation and example.
+%
+% \iitem{preview\underline{ }bibitem} Redefines |\bibtem| command. The
+% material between |\bibitem| and |\par| is wrapped to the width of
+% |0.75\textwidth| and extracted.
+%
+% \iitem{preview\underline{ }biblatex} Similarly like
+% |preview_bibitem| but works with |biblatex|.
+%
+% \iitem{ini} Inserted at the begin of each |pdflatex| run.
 %
-% \section{Troubleshooting and known problems}
+% \iitem{tooltips\underline{ }envelope\underline{ }preamble} Used in
+% preamble. Defines command |\tooltipwraper|. This command wraps the
+% tooltips. Default is to use |tikz| to put everything into a yellow
+% box with rounded corners and shading. 
+%
+% \iitem{biblatex} Creates temporary file
+% |fancy-preview-biblatex-settings.tex|. This file contains definition
+% which allow |biblatex| to work with citations and tooltips and we
+% input this file in final compilations. This code comes from
+% |tex.stackexchange.com|.
+%\end{itemize}
+%
+% 
+%
+% \subsection{Tips and tricks} 
+% \begin{itemize}
+% \item The program |pdfcrop| from \TeX live may produces large PDF
+%   files. See the discussion at
+%   \url{http://tex.stackexchange.com}\footnote{\url{http://tex.stackexchange.com/questions/42236/pdfcrop-generates-larger-file}}. The
+%   smaller size can be obtained with the solution from the discussion
+%   below the question, which is based on |gs| and |pdftk|. The
+%   |python| script from the same discussion produces slightly larger
+%   file than |pdftk|, but still much smaller than |pdfcrop| and
+%   provides the fastest solution.
+% \item Do not use floats in environments, which are
+%   extracted. Otherwise you get an error from \LaTeX. A workaround
+%   could be also to change temporarily definition of the floating
+%   environment (redefine |figure| environment, for example).
+% \item If you are not interested in customization via |ini| files and
+%   do not want to install extra modules to your Perl installation,
+%   you may delete the about twenty lines from |fancy-preview|
+%   starting with |use Config::IniFiles;| up to the line
+%   |read_config("./fancy-preview.ini");|
+% \end{itemize}
+%
+% \section{Troubleshooting and known problems}\label{sec:tr}
 % The source code is in Mercurial repository at
 % \url{http://bitbucket.org/robert.marik/fancytooltips/}. You can also
 % report problems and issues in the forum at this site. The code on
@@ -344,7 +591,7 @@
 % \item 
 %   The package works with |eforms.sty| from version
 %   2006/10/03 v1.0a. You can download this or newer version from
-%   www.arotex.net site.
+%   \url{http://www.acrotex.net} site.
 % \item If the graphics included by |\TooltipExtratext| and
 %   |\TooltipRefmark| has colors with \textbf{custom opacity}, Adobe
 %   Acrobat Pro sometimes renders the pictures bad. No problems of
@@ -427,6 +674,18 @@
 \newif\if@fancytooltips@fixcolor\@fancytooltips@fixcolorfalse
 \DeclareOptionX{fixcolor}{\@fancytooltips@fixcolortrue}
 
+\newif\if@fancytooltips@preview\@fancytooltips@previewfalse
+\DeclareOptionX{preview}{\@fancytooltips@previewtrue}
+
+\newif\if@fancytooltips@previewall\@fancytooltips@previewallfalse
+\DeclareOptionX{previewall}{\@fancytooltips@previewtrue\@fancytooltips@previewalltrue}
+
+\newif\if@fancytooltips@nosoap\@fancytooltips@nosoapfalse
+\DeclareOptionX{nosoap}{\@fancytooltips@nosoaptrue}
+
+\def\@@fancytipmark{}
+\DeclareOptionX{tooltipmark}{\xdef\@@fancytipmark{#1}}
+
 \def\fancytooltipsdebugmsg{}
 \DeclareOptionX{debug}{\def \fancytooltipsdebugmsg
 {
@@ -472,10 +731,9 @@ if (this.getField("animtiph") == null)
 \newcommand{\tooltip@NoStar}[2]{#1}%
 
 \newcommand{\tooltipanim}{\@ifstar\tooltipanim@Star\tooltipanim@NoStar}%
-\newcommand{\tooltipanim@Star}[2]{#1}%
-\newcommand{\tooltipanim@NoStar}[2]{#1}%
+\newcommand{\tooltipanim@Star}[3]{#1}%
+\newcommand{\tooltipanim@NoStar}[3]{#1}%
 \def\keytip#1{}%
-\def\FancyHook{}%
 \def\TooltipPage#1#2{}%
 \let\TooltipExtratext\relax
 \let\TooltipRefmark\relax
@@ -495,37 +753,71 @@ if (this.getField("animtiph") == null)
 \newcount\fancycheckcount\fancycheckcount=0
 \def\fancy@second#1#2#3#4{#2}
 
-\def\FancyHook{
+\def\fancypreview@refhook{%
 \global\let\oldref\ref
 \gdef\ref##1{\oldref{##1}\global\advance\fancycheckcount by 1\relax
 \edef\templabel{fancyanchorref:\the\fancycheckcount}%
 \expandafter\label\expandafter{\templabel}%
 \expandafter\ifx \csname FancyToolTip@##1\endcsname\relax \else\hbox to 0 pt{%
-\expandafter\ifx \csname r@##1\endcsname \relax\else
-\edef\temp{\csname r@##1\endcsname}%
-\expandafter\edef\expandafter\fan@tempa\expandafter{\expandafter\fancy@second\temp}%
-\fi
-\expandafter\ifx \csname r@fancyanchorref:\the\fancycheckcount\endcsname \relax\else
-\edef\fan@ttemp{r@fancyanchorref:\the\fancycheckcount}%
-\expandafter\let\expandafter\fan@temp@w\csname \fan@ttemp\endcsname
-\edef\fan@temp@ww{\expandafter\fancy@second\fan@temp@w}%
-\fi
-\ifx\fan@temp@ww\undefined\else
-\fi
+%    \end{macrocode}
+% Here we extract the page number for the label destination.
+%    \begin{macrocode}
+  \expandafter\ifx \csname r@##1\endcsname \relax\else
+    \expandafter\let\expandafter\fancytooltip@temp@a\csname r@##1\endcsname
+    \edef\fan@tempa{\expandafter\fancy@second\fancytooltip@temp@a}%
+  \fi
+%    \end{macrocode}
+% Here we extract the page number of the |\ref| command via faked label |fancyanchorref:\the\fancycheckcount|.
+%    \begin{macrocode}
+  \expandafter\ifx \csname r@fancyanchorref:\the\fancycheckcount\endcsname \relax\else
+    \expandafter\let\expandafter\fan@temp@w\csname r@fancyanchorref:\the\fancycheckcount\endcsname
+    \edef\fan@temp@ww{\expandafter\fancy@second\fan@temp@w}%
+    \fi
+%    \end{macrocode}
+% We print tooltip after |\ref| only if both |\label| and |\ref| commands are on different pages
+%    \begin{macrocode}
+\if@fancytooltips@previewall\def\fan@tempa{not a page number}\fi
 \ifx\fan@tempa\fan@temp@ww\else\smash{%
   \let\TooltipExtratext\relax\tooltip{\strut\TooltipRefmark}{##1}}%
 \fi
 \hss}%
-\fi}
-\ifTooltip@usepdftex
-\def\TooltipRefmark{\hbox {\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
-        {fancytipmark.pdf}}}}}%
+\fi}%
+%    \end{macrocode}
+% We replace the cite command. We test if natbib is loaded, if not, we redefine the command from article.cls. 
+%    \begin{macrocode}
+\ifx\NAT@citea@mbox\undefined
+\def\@citex[##1]##2{\leavevmode
+    \let\@citea\@empty
+    \@cite{\@for\@citeb:=##2\do
+      {\@citea\def\@citea{,\penalty\@m\ }%
+        \edef\@citeb{\expandafter\@firstofone\@citeb\@empty}%
+        \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi
+        \@ifundefined{b@\@citeb}{\hbox{\reset@font\bfseries ?}%
+          \G@refundefinedtrue
+          \@latex@warning
+          {Citation `\@citeb' on page \thepage \space undefined}}%
+        {\ifx\csname r@fancy:cite:\@citeb\endcsname\undefined \@cite@ofmt{\csname b@\@citeb\endcsname}\else\tooltip*{\@cite@ofmt{\csname b@\@citeb\endcsname}}{fancy:cite:\@citeb}\fi
+        }}}{##1}}%
 \else
-\def\TooltipRefmark{\hbox {\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
-        {fancytipmark.eps}}}}}%
-\fi%\ifTooltip@usepdftex
+\def\NAT@citea@mbox{%
+ \@citea\mbox{\NAT@hyper@{{\citenumfont{\NAT@num}}}}\tooltip*{}{fancy:cite:\@citeb}}
+\fi
 }
 
+\if@fancytooltips@nosoap
+  \def\TooltipRefmark{\hbox{\ }}%
+\else
+  \ifTooltip@usepdftex
+  \def\TooltipRefmark{\hbox {\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
+          {fancytipmark\@@fancytipmark.pdf}}}}}%
+  \else
+  \def\TooltipRefmark{\hbox {\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
+          {fancytipmark.eps}}}}}%
+  \fi%\ifTooltip@usepdftex
+\fi%\if@fancytooltips@nosoap
+
+\if@fancytooltips@preview\AtBeginDocument{\fancypreview@refhook}\fi
+
 \if@fancytooltips@createtips
 %    \end{macrocode}
 % This part (three lines) is processed if the option |createtips| is
@@ -552,12 +844,17 @@ if (this.getField("animtiph") == null)
 \ifTooltip@usepdftex
 \RequirePackage[pdftex]{eforms}
 \def\TooltipExtratext{\hbox{\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
-        {fancytipmark.pdf}}}}}
+        {fancytipmark\@@fancytipmark.pdf}}}}}
 \else
 \RequirePackage[dvips]{eforms}
 \def\TooltipExtratext{\hbox{\smash{\raisebox{0.4em}{\includegraphics[width=0.7em]%
         {fancytipmark.eps}}}}}
 \fi%\ifTooltip@usepdftex
+
+\if@fancytooltips@nosoap
+  \def\TooltipExtratext{\hbox{\ }}%
+\fi%\if@fancytooltips@nosoap
+
 \if@fancytooltips@extratext\else\let\TooltipExtratext\relax\fi
 
 \AtBeginDocument{ 
@@ -613,7 +910,8 @@ if (this.getField("animtiph") == null)
     \def\@ocg@makeknown#1#2#3{}\fi
 \fi
 
-\if@fancytooltips@fg\else
+\if@fancytooltips@fg
+\else
 \RequirePackage{eso-pic}
 \def\frametip{%
   \expandafter\ifx \csname TooltipPage\thepage\endcsname\relax
@@ -627,6 +925,7 @@ if (this.getField("animtiph") == null)
 \def\fancytooltips@save@position{\pdfsavepos%
   \write\@auxout{\string\global\string \fancy@layerVshift \the\pdflastypos sp\string\relax}%
   \write\@auxout{\string\global\string \fancy@layerHshift \the\pdflastxpos sp\string\relax}%
+  \global\let\fancytooltips@save@position\relax%
 }
 
 \def\fancy@beginshipout@hook{}
@@ -635,7 +934,7 @@ if (this.getField("animtiph") == null)
 \setbox\AtBeginShipoutBox=\hbox{%    
   \hbox to 0 pt{\TooltipHidden}\global\def\TooltipHidden{}%
   \fancy@beginshipout@hook\if@fancytooltips@fixcolor\hbox to 0 pt{\resizebox{1pt}{!}{\TooltipExtratext}\hss}\fi
-  \hbox{\box\AtBeginShipoutBox}%
+  \hbox to 0 pt{\box\AtBeginShipoutBox\hss}%
   \ifTooltip@usepdftex 
     \fancytooltips@save@position
     \if@fancytooltips@blur
@@ -647,16 +946,16 @@ if (this.getField("animtiph") == null)
           \vbox to 0 pt{\vss\hbox{\vrule width \paperwidth height \paperheight}}%
         \end{ocg}\hss}%
       \fi
-    \fi
+    \fi%\if@fancytooltips@blur
     \if@fancytooltips@fg
-    \expandafter\ifx \csname TooltipPage\thepage\endcsname\relax
-    \else
-      \lower\fancy@layerVshift\vbox to 0 pt{\vss\hbox to 0 pt{\kern-\fancy@layerHshift\relax\hbox{\frametip@}\hss}}%
-    \fi
-    \lower\fancy@layerVshift\vbox to 0 pt{\vss\hbox to 0 pt{\kern-\fancy@layerHshift\relax\hbox to 0 pt{\the\pos@fancy@toks\hss}}}%
-    \fi
-  \fi
- }%
+      \expandafter\ifx \csname TooltipPage\thepage\endcsname\relax
+      \else
+        \lower\fancy@layerVshift\vbox to 0 pt{\vss\hbox to 0 pt{\kern-\fancy@layerHshift\relax\hbox{\frametip@}\hss}}%
+      \fi%\ifx
+      \lower\fancy@layerVshift\vbox to 0 pt{\vss\hbox to 0 pt{\kern-\fancy@layerHshift\relax\hbox to 0 pt{\the\pos@fancy@toks\hss}\hss}}%
+    \fi%\if@fancytooltips@fg
+  \fi%\ifTooltip@usepdftex
+  \kern\hsize}%
 }%
 
 %    \end{macrocode}