path: root/Master/texmf-dist/source/latex/spot/spot.dtx

% \iffalse meta-comment
%
% spot.ins
% Copyright 2010 by Anders O.F. Hendrickson (ahendric@cord.edu)
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Anders O.F. Hendrickson.
%
% This work consists of the files spot.dtx and spot.ins
% and the derived file spot.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{spot.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{spot}
%<*package>
    [2011/05/09 v1.1 Spotlight highlighting]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{spot}
\usepackage{fancyvrb}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{spot.dtx}
  \PrintChanges
  %\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{360}
%
% \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}{2010/09/21}{Initial version}
%
% \GetFileInfo{spot.sty}
%
% \DoNotIndex{\newcommand,\newenvironment,\def}
% 
%
% \title{The \textsf{spot} package: \\
%        spotlight highlighting for Beamer\thanks{This document
%   corresponds to \textsf{spotlight}~\fileversion, dated \filedate.}}
% \author{Anders Hendrickson\\ Concordia College, Moorhead, MN \\ \texttt{ahendric@cord.edu}}
%
% \maketitle
%
% \providecommand\barg[1]{%
% {\ttfamily\char`<}\meta{#1}{\ttfamily\char`>}}
% \providecommand\TikZ{Ti\emph{k}Z}
%
% \section{Introduction}
%
% 
% Beamer's |\alert| command is designed to call the viewer's attention
% to certain parts of the slide, but under some circumstances it can be less effective than desired.
% First, because the actual colors produced depend on the projector 
% hardware used and the ambient lighting in the room,
% you can find to your dismay that the color change 
% provided by |\alert| is barely discernible onscreen.
% Of course you can fiddle with |\setbeamercolor{alerted text}|\marg{color}
% to achieve better results on your own projector,
% but you may still face surprises when taking your presentation to another institution.
% Moreover, the |\alert| command is often ineffective at highlighting
% just one or two characters on a full slide;
% in such a situation, 
% a color change alone may not be striking enough to draw the viewer's eye.
% For just such circumstances, this package provides a |\spot| command 
% to paint a ``spotlight'' of color painted behind the highlighted text, 
% as in \spot{this example.}
% 
%
%
% \section{Usage}\label{sect:usage}
% \subsection{General Usage}
%
%
% \DescribeMacro{\spot}
% The |\spot| command has the following syntax:
% \begin{center}
% |\spot|\barg{overlay spec}\parg{node name}\oarg{node options}\marg{highlighted text}
% \end{center}
% The first three parameters, \barg{overlay spec}, \parg{node name}, and \oarg{node options}, 
% are optional,
% and any combination of them may be omitted,
% but their order must not change.
% For example, |\spot<5->[fill=red]{George}| is legal,
% but entering |\spot[star](mynode){Joe}| will produce erroneous output.
%
% The \meta{overlay spec} should be a standard Beamer overlay specification;
% for example,
% |\spot<2-3>{Fred}| highlights the word ``Fred'' only on slides 2 and 3.
% The actual ``spotlight'' shape is a \TikZ\ node.
% If you wish to access the node 
% later---for example, to point an arrow at it---you
% can specify a \meta{node name}.
% Consider the following example:
% \begin{quote}
% \begin{tabular}{p{1.5in}p{3in}}
% \spot*(first){We} can draw an arrow from the first word of this sentence to the \spot*(last){last}.
% \tikz[remember picture, overlay]{\draw (first) to[->] (last);}
% & \tt
% |\spot(first){We}| can draw an arrow from the first word of this sentence to the |\spot(last){last}.|
% |\tikz[remember picture, overlay]{| | \draw (first) to[->] (last);}|
% \end{tabular}
% \end{quote}
% \dospots
%
%
% The default behavior of |\spot| is to surround its argument with a gold-colored ellipse,
% most intense at its center and fading towards the edges.
% That behavior can be altered---for example, to change the shape or color---for 
% a specific instance of |\spot| by specifying \meta{node options}.
% Consider the following example:
% \begin{quote}
% \begin{tabular}{p{1.5in}p{3in}}
% To \spot*[fill=blue!50]{be,}
% or not to
% \spot*[star, star points=8]{be:}
% that \spot*[ball color=red]{is} the 
% \spot*[path fading=east]{question.}
% & \tt
% To |\spot*[fill=blue!50]{be,}|
% or not to
% |\spot*[star, star points=8]{be:}|
% that |\spot*[ball color=red]{is}| the 
% |\spot*[path fading=east]{question.}|
% \end{tabular}
% \end{quote}
% \dospots
%
% For a complete understanding of possible \meta{node options},
% please see the PGF/\TikZ\ documentation.
% Of particular note is that |path fading=none| will eliminate the fading,
% causing the node to \spot*[path fading=none]{overlap} surrounding text.
% To change the default behavior for subsequent calls to |\spot|, 
% the following commands are provided.
%
% \DescribeMacro{\setspotlightcolor}
% \DescribeMacro{\resetspotlightcolor}
% \DescribeMacro{\spotlightcolor}
% The command |\setspotlightcolor|\marg{color} makes all subsequent invocations of |\spot|
% use the specified \meta{color}.
% The default shade of gold is named |spotlightgold|, 
% and may be restored with the command |\resetspotlightcolor|.
% The current color is saved in the macro |\spotlightcolor|,
% making commands such as |\setspotlightcolor{\spotlightcolor!50}| possible.
% Note that if |fill=|\meta{color} is given in the \meta{node options}
% or with |\setspotlightstyle|, 
% it takes precedence over the \meta{color} in |\spotlightcolor|.
%
% \DescribeMacro{\setspotlightstyle}
% \DescribeMacro{\resetspotlightstyle}
% \DescribeMacro{\spotlightnodeoptions}
% The command |\setspotlightstyle|\marg{node options} adds \meta{node options} 
% to the nodes produced by all subsequent invocations of |\spot|.
% The effect of multiple calls is cumulative.
% Default options may be restored by
% |\resetspotlightstyle|.
% The current options are saved in the macro |\spotlightnodeoptions|.
% 
% \begin{quote}
% \begin{tabular}{p{1.5in}p{3in}}
% & |\setspotlightcolor{red!50}| \\
% & |\spot{A} \quad| \\
% & |\setspotlightstyle{star, fill=green!50}| \\
% & |\spot{B} \quad| \\
% \setspotlightcolor{red!50}
% \spot*{A} \quad
% \setspotlightstyle{star, fill=green!50}
% \spot*{B} \quad
% \setspotlightstyle{star points=7}
% \spot*{C} \quad
% \resetspotlightstyle
% \spot*{D} \quad
% \resetspotlightcolor
% \spot*{E}
% & |\setspotlightstyle{star points=7}| \\
% & |\spot{C} \quad| \\
% & |\resetspotlightstyle \spot{D} \quad| \\
% & |\resetspotlightcolor \spot{E}| \\
% \end{tabular}
% \end{quote}
% \resetspotlightcolor
% \dospots
%
% \subsection{Non-Beamer Usage}\label{sect:nonbeamerusage}
%
% Although the |spot| package is chiefly designed for use with Beamer,
% it may also be used in documents
% of other classes.
% There are two peculiarities,\label{page:2pec} 
% however, the reasons for which will be explained in section \ref{sect:strategy}.
% \DescribeMacro{\spot*}
% First, if |\spot| is used within a |\parbox|,
% a |minipage| environment,
% a header or footer,
% or a |p| column in a |tabular| environment,
% the error message
% ``|LaTeX Error: Float(s) lost|'' will result.
% The remedy is to use the the starred version |\spot*| instead,
% and to follow the instructions in the following paragraph.
%
% \DescribeMacro{\dospots}
% Second, if the last call to |\spot| on a page is
% in math mode, in a \TeX\ inner mode (such as a |tabular| environment),
% or the starred version |\spot*|,
% then the command |\dospots| must be issued somewhere later on that same page,
% after the math mode or |tabular| or |\parbox| has ended.
% (The actual criterion is that |\dospots| must be able to call |\marginpar|,
% which cannot be done in those environments.)
% If the page ends before a |\dospots| is encountered, 
% an error message will be generated.
% 
% \DescribeMacro{\dospotsheader}
% \DescribeMacro{\dospotsfooter}
% Remembering to place a |\dospots| after each problematic |\spot|
% can be a hassle.
% The best solution is to use the |fancyhdr| package
% to place the command |\dospotsheader|
% or its synonym |\dospotsfooter|
% into a header or footer appearing on every page,
% obviating the need for any manual |\dospots|.
% Moreover, if a spotlight is desired \emph{within} a header, footer, or marginpar, 
% |\spot*| should be used and |\dospotsheader| or |\dospotsfooter| should follow.
%
% 
%
% 
% \section{Strategy}\label{sect:strategy}
% \VerbatimFootnotes
% This section describes the mechanism |spot| uses to draw its spotlights.
% It would be simple enough to wrap the 
%  \makeatletter
%  \tikz[baseline]{
%     \path[use as bounding box] 
%                    node[anchor=base, inner sep=0, outer sep=0, opacity=0] 
%                    (temp) {highlighted text};
%              \path (temp) 
%                    node[anchor=center, outer sep=0,
%                         shape=ellipse, inner sep=0.5ex, 
%                         fill=\spotlightcolor, path fading=spot@fade] {highlighted text};
%    }
%  \makeatother
% within a \TikZ\ node, keeping it in line with its surroundings,
% but the result is not perfect.  The preceding highlighting\footnote{Produced with
%  \begin{verbatim}
%    \tikz[baseline]{
%      \path[use as bounding box] 
%        node[anchor=base, inner sep=0, outer sep=0, opacity=0] 
%         (temp) {highlighted text};
%      \path (temp) 
%        node[anchor=center, outer sep=0,
%             shape=ellipse, inner sep=0.5ex, 
%             fill=\spotlightcolor, path fading=spot@fade] {highlighted text};}
%  \end{verbatim}
% }
% was painted over previous text
% but under subsequent text, creating both an uneven effect
% and an unintentional emphasis on the beginning of the following word.
% The solution is to leave a blank space in the text,
% coming back once the entire frame has been typeset
% to draw the text and its highlighting over their surroundings.
% 
% Suppose then that |\spot<2>{foo}| is called in a Beamer frame.
% On slide 1 of the frame,
% the text |foo| is typeset as the sole node in a \TikZ\ picture,
% with node options chosen so that it occupies
% its place in the paragraph just like ordinary typeset text.
% The node is given a name such as |spot@vii|,
% and the |remember picture| option is used.
%
% When slide 2 is typeset,
% the node |spot@vii| is drawn as before, except with |opacity=0| so that it is transparent.
% After the contents of the entire slide are typeset,
% another \TikZ\ picture uses the |overlay| option 
% to return to the location of |spot@vii|
% and typeset |foo| in a node with 
% a suitably eye-catching shape, |fill| color, and fading.
%
% In Beamer, the code to paint the highlighted node is attached to |\end{frame}|.
% The challenge for implementing |spot| in classes other than Beamer
% is the lack of a hook for the end of a page;
% even the |afterpage| package cannot return to the previous page to typeset new material.
% The solution used is to insert the |\spot@paintspot| macro
% into a |\marginpar|.
% This is the source of the two peculiarities mentioned on page \pageref{page:2pec},
% for under certain circumstances, \LaTeX\ cannot process a |\marginpar|
% correctly.
% These circumstances include \TeX's inner vertical mode, display math, and |\parbox|es.
% In these situations 
% |spot| must save its painting commands for later.
% The command |\dospots|, called from a ``safe'' location,
% inserts those saved commands into a |\marginpar|.
% The alternative commands |\dospotsheader| and |\dospotsfooter|
% execute the saved paint commands immediately,
% making them suitable for inclusion in a header or footer.
% Because this second mechanism, though more reliable, 
% places an extra burden on the user, 
% it was not chosen as the default behavior for |\spot|.
%
% The starred version |\spot*| uses the second mechanism in place of the first.
% Moreover, the |\spot| macro will also switch to the second mechanism
% when it can detect the necessity.
% If |\ifinner| is true, then |\marginpar| would fail;
% likewise if |\ifmmode| is true, then \LaTeX\ might well be in display math mode
% where |\marginpar| fails;
% in these situations, |\spot| acts like |\spot*|.
% Unfortunately, if |\spot| is called within a |\parbox|, 
% there is no test that can make |\spot| aware of that fact,
% and the user will see
% |LaTeX Error:  Float(s) lost.|
% This warning is an indication that even \LaTeX\ itself could not tell in advance
% whether |\marginpar| would work properly or not.
% 
% 
%
% \section{Limitations and Tips}
% \begin{itemize}
%
% \item Because |\spot{foo}| places the text |foo| in a \TikZ\ node,
% it will not allow line breaks within |foo|.
% For highlighting that permits automatic line breaking, consider the |\hl| command of the |soul| package.
%
% \item The |\spot| command does not work well in a Beamer frame
% broken into multiple slides by |allowframebreaks|.
%
% \item In non-Beamer class, spotlights meant for the bottom of one page
% may sometimes show up at the bottom of the next page.
% 
% 
%
% \item It is possible to call |\spot| in math mode, 
% but as the argument will be set in a box within a \TikZ\ node,
% the results may need tinkering.
% For example, |$a^{\spot{b}}$| produces $a^{\spot{b}}$,
% not $a^{\spot{\scriptstyle b}}$;
% to make the superscript the correct size,
% you must write |$a^{\spot{\scriptstyle b}}$|.
% Likewise to produce $a\mathbin{\spot{=}}b$ requires writing
% |$a\mathbin{\spot{=}}b$|, since merely writing
% |$a\spot{=}b$| produces the poorly spaced $a\spot{=}b$.
% \dospots
%
% \item As mentioned in section \ref{sect:nonbeamerusage},
% when using |spot| in a document class other than Beamer,
% it is best to include |\dospotsheader| in a header appearing on every page.
% A minimal solution is to put the following in the preamble:
% \begin{verbatim}
%   \usepackage{fancyhdr}
%   \pagestyle{fancy}
%   \fancyhf{}
%   \rhead{\dospotsheader}
% \end{verbatim}
% \end{itemize}
% 
% 
% \StopEventually{}
%
% \section{Implementation}
% 
% \subsection{Packages and Hooks}
%
% The \TikZ\ package must be loaded with the necessary libraries.
%    \begin{macrocode}
\RequirePackage{tikz}
\usetikzlibrary{shapes}
\usetikzlibrary{fadings}
%    \end{macrocode}
%
% We next check whether we are in the Beamer class
% or not, and we abbreviate |\expandafter| in the usual way.
%    \begin{macrocode}
\newif\ifspot@beamer
\@ifundefined{beamer@frameslide}{\spot@beamerfalse}{\spot@beamertrue}
\let\xa=\expandafter
%    \end{macrocode}
%
% In Beamer, we will need hooks for running code at the beginning and end of each frame.
% The commands |\AtEveryBeginFrame| and |\AtEveryEndFrame| store commands to be run in every frame,
% \changes{v1.1}{2011/05/09}{Fixed bug with Beamer's title command}
% while the command |\AtEndFrame| applies only to the current frame.
% We repeat the last token of |\beamer@frameslide|, namely |\beamer@checkframetitle|,
% so that |\beamer@frameslide| can still detect the presence of a frame title.
%    \begin{macrocode}
\ifspot@beamer
  \g@addto@macro\beamer@frameslide{\spot@everybeginframe@hook\beamer@checkframetitle}
%    \end{macrocode}
% Whereas |\g@addto@macro| makes it easy to add
% |\spot@everybeginframe@hook| to the end of the |\begin{beamer@frameslide}| code,
% adding hooks to be executed right \emph{before}
% the existing |\end{beamer@frameslide}| code is a little more involved.
%    \begin{macrocode}
  \let\spot@oldmaterial=\endbeamer@frameslide
  \def\spot@newmaterial{%
        \spot@endframe@hook%
        \gdef\spot@endframe@hook{}%
        \spot@everyendframe@hook}
  \xa\xa\xa\def
  \xa\xa\xa\endbeamer@frameslide
  \xa\xa\xa{%
        \xa\spot@newmaterial\spot@oldmaterial}%
%    \end{macrocode}
% Having placed hooks into the |beamer@frameslide| environment,
% we now initialize those hooks as empty
% and create the commands |\AtEndFrame|, |\AtEveryEndFrame|, and |\AtEveryBeginFrame|.
%    \begin{macrocode}
  \def\spot@endframe@hook{}
  \def\spot@everyendframe@hook{}
  \def\spot@everybeginframe@hook{}
  \long\def\AtEndFrame#1{\g@addto@macro\spot@endframe@hook{#1}}
  \long\def\AtEveryEndFrame#1{\g@addto@macro\spot@everyendframe@hook{#1}}
  \long\def\AtEveryBeginFrame#1{\g@addto@macro\spot@everybeginframe@hook{#1}}
%    \end{macrocode}
% In classes other than Beamer, we will need the |afterpage| package to run code between pages.
%    \begin{macrocode}
\else
  \RequirePackage{afterpage}
\fi
%    \end{macrocode}
%
%
%
% \subsection{Spotlight options}
% We next define the options.  
% The |\spotlightcolor| macro stores the working color;
% it can be edited with the commands |\setspotlightcolor| and |\resetspotlightcolor|.
%    \begin{macrocode}
\def\spotlightcolor{spotlightgold}
\def\setspotlightcolor#1{\xdef\spotlightcolor{#1}}
\def\resetspotlightcolor{\gdef\spotlightcolor{spotlightgold}}
%    \end{macrocode}
% Likewise the command |\spotlightnodeoptions| stores additional node options chosen by the user.
% The command |\setspotlightstyle| adds to it, and |\resetspotlightstyle| empties it.
%    \begin{macrocode}
\def\spotlightnodeoptions{}
\def\setspotlightstyle#1{\g@addto@macro\spotlightnodeoptions{#1, }}
\def\resetspotlightstyle{\gdef\spotlightnodeoptions{}}
%    \end{macrocode}
% Finally, here are the default color and fading.
%    \begin{macrocode}
\definecolor{spotlightgold}{RGB}{255,204,51}
\tikzfading[name=spot@fade,
            inner color=transparent!0,
            outer color=transparent!60]
%    \end{macrocode}
% The count register |\c@spot@spots| numbers each spotlight on the frame or page.
%    \begin{macrocode}
\newcount\c@spot@spots
\c@spot@spots=1
\ifspot@beamer
  \AtEveryBeginFrame{\global\c@spot@spots=1\relax}
\else
  \afterpage{\global\c@spot@spots=1\relax}
\fi
%    \end{macrocode}
%
%
%
%
% \subsection{Input parsing}
% \begin{macro}{\spot}
% The macro |\spot| comes in starred and unstarred versions.
% We first check for the presence of the star,
% and set a flag if it is present.
%    \begin{macrocode}
\newif\ifspot@star
\spot@starfalse
\def\spot{\@ifnextchar*{\spot@star}{\spot@nostar}}
\def\spot@star#1{\global\spot@startrue\spot@nostar}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@nostar}
% As described in section \ref{sect:usage}, 
% the full syntax of |\spot| is 
%   \begin{center}
%     |\spot|\barg{overlay spec}\parg{node name}\oarg{node options}\marg{highlighted text}
%   \end{center}
% with each of \meta{overlay spec}, \meta{node name}, and \meta{node options} being optional.
% If any is not specified, we fill in the appropriate default value.
%
% The default overlay specification is |<1->|. 
%    \begin{macrocode}
\def\spot@nostar{%
  \@ifnextchar<{\spot@in}{\spot@in<1->}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@in}
% The default \meta{node name} is |spot@dummynode|.
%    \begin{macrocode}
\def\spot@in<#1>{%
  \@ifnextchar({\spot@inte<#1>}%
               {\spot@inte<#1>(spot@dummynode)}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@inte}
% The default is to have no extra \meta{node options}.
%    \begin{macrocode}
\def\spot@inte<#1>(#2){%
  \@ifnextchar[{\spot@intern<#1>(#2)}{\spot@intern<#1>(#2)[]}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@intern}
% Because the spotlight is painted after the rest of the page is drawn,
% it is important to expand the node options now
% (including |\spotlightcolor| and the user-defined |\spotlightnodeoptions|),
% so that they will not be affected by redefinitions later on the page.
% Note that the order of parameters is changed to make the |\expandafter|s work.
%    \begin{macrocode}
\def\spot@intern<#1>(#2)[#3]#4{%
  \edef\spot@totaloptions{fill=\spotlightcolor, \spotlightnodeoptions, #3}%
  \xa\spot@internal\xa[\spot@totaloptions]<#1>(#2){#4}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@internal}
% Finally, we are ready to call the macros which actually do the work,
% depending on whether we are running Beamer or some other class.
% We return the parameters to their normal order.
%    \begin{macrocode}
\def\spot@internal[#1]<#2>(#3)#4{%
  \ifspot@beamer%
    \spot@internal@beamer<#2>(#3)[#1]{#4}%
  \else%
    \spot@internal@static<#2>(#3)[#1]{#4}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
%
%
%
%
% \subsection{Beamer version}
%
% \begin{macro}{\spot@internal@beamer}
% The macro |\spot@internal@beamer|
% implements the |\spot| command when used in a Beamer presentation.
%    \begin{macrocode}
\def\spot@internal@beamer<#1>(#2)[#3]#4{%
%    \end{macrocode}
% The text to be highlighted is first saved in a box named something like |\spot@box@vii|,
% where the roman numeral represents the spot counter |\c@spot@spots|.
% In this way it will automatically have the correct font size and shape (italics, boldface, etc.).
% It is set in math mode if necessary.
% For the sake of readability of the code, |\spot@currentbox| is let equal to |\spot@box@vii|.
%    \begin{macrocode}
  \@ifundefined{spot@box@\romannumeral\c@spot@spots}%
          {\xa\newbox\csname spot@box@\romannumeral\c@spot@spots\endcsname}{}%
  \ifmmode
    \global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{$#4$}%
  \else
    \global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{#4}%
  \fi
  \xa\let\xa\spot@currentbox\csname spot@box@\romannumeral\c@spot@spots\endcsname%
%    \end{macrocode}
% Now we are ready to set the text.
% On the highlighted slides, we actually produce two \TikZ\ nodes at this time.
% The first is merely a transparent copy of the text itself;
% the second is a transparent copy of the entire highlighted node shape,
% and receives the \meta{node name} called by the user.
% We require the first node (with the |use as bounding box| option) 
% so as to fit the text seamlessly in line with its surroundings.
% The second node, bearing \meta{node name}, must be drawn now, so that the user can 
% refer to \meta{node name}
% within the frame;
% the \meta{node name} could not simply be attached to the visible spotlight,
% since that is drawn with |\AfterEndFrame|, \emph{after} all the user's code has been processed.
% On unhighlighted slides, we simply draw an opaque copy of the text in a \TikZ\ node.
%    \begin{macrocode}
  \tikz[remember picture, baseline]{
    \alt<#1>{\path[use as bounding box] 
                   node[anchor=base, inner sep=0, outer sep=0, opacity=0] 
                   (spot@\romannumeral\c@spot@spots) {\usebox\spot@currentbox};
             \path (spot@\romannumeral\c@spot@spots) 
                   node[anchor=center, outer sep=0,
                        shape=ellipse, inner sep=0.5ex, 
                        #3, opacity=0] (#2) {\usebox\spot@currentbox};}
            {\path node[anchor=base, inner sep=0, outer sep=0, opacity=1]
                       (#2) {\usebox\spot@currentbox};}
    }%
%    \end{macrocode}
% Finally, we save the information needed to paint the spotlight at the end of the slide.
% Sometimes calling |\AtEndFrame|
% adds a little extra height to the frame's contents,
% which could cause a slight movement of the frame between highlighted and unhighlighted slides.
% We therefore make a call to |\AtEndFrame| on unhighlighted slides
% as well, to ensure that the same extra height be added
% even when we're not painting spotlights.
%    \begin{macrocode}
  \alt<#1>{\xa\spot@savepaint\xa{\romannumeral\c@spot@spots}[#3]}%
          {\AtEndFrame{\rule{0pt}{0pt}}}%
%    \end{macrocode}
% Finally, we increment the counter |\c@spot@spots| and end the macro.
%    \begin{macrocode}
  \global\advance\c@spot@spots by 1\relax%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@savepaint}
% The following macro saves the actual spotlight-drawing command to be executed at the end of the slide.
% The first parameter is a roman numeral labeling the spotlight,
% while the second contains the node options.
%    \begin{macrocode}
\def\spot@savepaint#1[#2]{%
  \AtEndFrame{\spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@paintspot}
% The command |\spot@paintspot| actually draws the spotlight at the saved location.
% Note that the first parameter is not the user-specified \meta{node name},
% but an automatically generated name such as |spot@vii|.
%    \begin{macrocode}
\def\spot@paintspot(#1)[#2]#3{%
  \begin{tikzpicture}[remember picture, overlay, baseline]
      \path (#1) node[anchor=center, outer sep=0,
                      shape=ellipse, inner sep=0.5ex, text opacity=1, 
                      path fading=spot@fade, text=black, #2] {#3};
  \end{tikzpicture}%
}
%    \end{macrocode}
% \end{macro}
%
%
%
% \subsection{non-Beamer version}
% To make the spotlight turn out correctly,
% it is vital to run |\spot@paintspot| \emph{after} all surrounding text has been typeset.
% Whereas in Beamer the code can be attached to 
% a hook in the |\end{frame}|,
% in other document classes
% we place the code in a |\marginpar|,
% which (being a \TeX\ insertion) is typeset after the rest of the page.
% If |\spot| is called in certain \TeX\ modes, however,
% |\marginpar| would produce an error.
% In this case, |\spot| saves up the commands to be placed into a |\marginpar| later.
% \begin{macro}{\spot@savedpaintcommands}
% \begin{macro}{\dospots}
% Whenever |\spot| is called, the |\spot@paintspot| commands 
% will be saved up in the macro |\spot@savedpaintcommands|.
% A subsequent call to |\dospots|, by the user if necessary, 
% executes those commands and resets the macro to empty.
%    \begin{macrocode}
\gdef\spot@savedpaintcommands{}
\def\dospots{%
  \marginpar{\spot@savedpaintcommands}%
  \gdef\spot@savedpaintcommands{}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\dospotsheader}
% \begin{macro}{\dospotsfooter}
% Since headers and footers are also \TeX\ insertions,
% the |\spot@savedpaintcommands| could also be run there.
% The following commands are synonyms.
%    \begin{macrocode}
\def\dospotsheader{%
  \spot@savedpaintcommands%
  \gdef\spot@savedpaintcommands{}%
}
\let\dospotsfooter=\dospotsheader
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\spot@internal@static}
% Much of the code in |\spot@internal@static| is identical with that of |\spot@internal|.
% The chief difference is that the overlay specification is completely ignored.
%    \begin{macrocode}
\def\spot@internal@static<#1>(#2)[#3]#4{%
  \@ifundefined{spot@box@\romannumeral\c@spot@spots}%
          {\xa\newbox\csname spot@box@\romannumeral\c@spot@spots\endcsname}{}%
  \ifmmode
    \global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{$#4$}%
  \else
    \global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{#4}%
  \fi
  \xa\let\xa\spot@currentbox\csname spot@box@\romannumeral\c@spot@spots\endcsname%
  \tikz[remember picture, baseline]{
     \path[use as bounding box] 
            node[anchor=base, inner sep=0, outer sep=0, opacity=0] 
            (spot@\romannumeral\c@spot@spots) {\usebox\spot@currentbox};
     \path (spot@\romannumeral\c@spot@spots)
             node[anchor=center, inner sep=0, outer sep=0,
                  shape=ellipse, inner sep=0.5ex, 
                  #3, opacity=0] (#2) {\usebox\spot@currentbox};
    }%
  \xa\spot@static@savepaint\xa{\romannumeral\c@spot@spots}[#3]%
  \global\advance\c@spot@spots by 1\relax%
  \global\spot@starfalse%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@static@savepaint}
% When |\spot@static@savepaint| is called, it first checks whether \TeX\ is in
% an inner mode and/or math mode, and whether the starred version |spot*| was used.  
% If any of these three conditions holds, a call to |\marginpar| would likely fail,
% so the |\marginpar| command is saved to be executed by a |\dospots| command sometime later,
% and |\spot@checkforlostspots| will be run after the current page is processed.
% Otherwise, 
% the appropriate |\spot@paintspot| command is immediately placed in a |\marginpar|,
% and any saved |\marginpar| commands are run at this time with |\dospots|.
% As with |\spot@savepaint|, the first parameter is
% the roman numeral identifying which spotlight is being painted,
% and the second contains the node options.
%    \begin{macrocode}
\def\spot@static@savepaint#1[#2]{%
  \def\spot@saveit{%
    \g@addto@macro\spot@savedpaintcommands{%
      \spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}%
    \afterpage{\spot@checkforlostspots}%
  }%
  \ifspot@star
    \spot@saveit
  \else
    \ifinner
      \spot@saveit
    \else
      \ifmmode
        \spot@saveit
      \else
        \marginpar{\spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}%
        \dospots
      \fi
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\spot@checkforlostspots}
% Between pages, the command |\spot@checkforlostspots| checks whether any 
% |\spot@paintspot| commands were saved into |\spot@savedpaintcommands| but never 
% executed by a |\dospots|.  If so, it issues an error message to the user.
%    \begin{macrocode}
\def\spot@checkforlostspots{%
  \def\spot@empty{}%
  \ifx\spot@savedpaintcommands\spot@empty%
    \relax%
  \else%
    \bgroup
    \advance\count0 by -1
    \PackageError{spot}%
       {A \protect\dospots\space command is missing 
        from page \the\count0.\MessageBreak
        Some highlighted text will not appear in the output}%
       {If the last \protect\spot\space command on a 
        page is issued in math mode or a \MessageBreak
        TeX inner mode (such as a tabular environment), 
        it must be followed by a \MessageBreak
        \protect\dospots\space command somewhere later 
        on the page, outside such a mode.\MessageBreak
        You could also put \protect\dospotsheader\space 
        in a header or footer on each page.}
    \egroup
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
%
% \Finale
\endinput