| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% spot.ins |
| 4 |
% Copyright 2010 by Anders O.F. Hendrickson ([email protected]) |
| 5 |
% |
| 6 |
% This work may be distributed and/or modified under the |
| 7 |
% conditions of the LaTeX Project Public License, either version 1.3 |
| 8 |
% of this license or (at your option) any later version. |
| 9 |
% The latest version of this license is in |
| 10 |
% http://www.latex-project.org/lppl.txt |
| 11 |
% and version 1.3 or later is part of all distributions of LaTeX |
| 12 |
% version 2005/12/01 or later. |
| 13 |
% |
| 14 |
% This work has the LPPL maintenance status `maintained'. |
| 15 |
% |
| 16 |
% The Current Maintainer of this work is Anders O.F. Hendrickson. |
| 17 |
% |
| 18 |
% This work consists of the files spot.dtx and spot.ins |
| 19 |
% and the derived file spot.sty. |
| 20 |
% |
| 21 |
% \fi |
| 22 |
% |
| 23 |
% \iffalse |
| 24 |
%<*driver> |
| 25 |
\ProvidesFile{spot.dtx} |
| 26 |
%</driver> |
| 27 |
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] |
| 28 |
%<package>\ProvidesPackage{spot} |
| 29 |
%<*package> |
| 30 |
[2011/05/09 v1.1 Spotlight highlighting] |
| 31 |
%</package> |
| 32 |
% |
| 33 |
%<*driver> |
| 34 |
\documentclass{ltxdoc} |
| 35 |
\usepackage{spot} |
| 36 |
\usepackage{fancyvrb} |
| 37 |
\EnableCrossrefs |
| 38 |
\CodelineIndex |
| 39 |
\RecordChanges |
| 40 |
\begin{document} |
| 41 |
\DocInput{spot.dtx} |
| 42 |
\PrintChanges |
| 43 |
%\PrintIndex |
| 44 |
\end{document} |
| 45 |
%</driver> |
| 46 |
% \fi |
| 47 |
% |
| 48 |
% \CheckSum{360} |
| 49 |
% |
| 50 |
% \CharacterTable |
| 51 |
% {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 |
| 52 |
% 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 |
| 53 |
% Digits \0\1\2\3\4\5\6\7\8\9 |
| 54 |
% Exclamation \! Double quote \" Hash (number) \# |
| 55 |
% Dollar \$ Percent \% Ampersand \& |
| 56 |
% Acute accent \' Left paren \( Right paren \) |
| 57 |
% Asterisk \* Plus \+ Comma \, |
| 58 |
% Minus \- Point \. Solidus \/ |
| 59 |
% Colon \: Semicolon \; Less than \< |
| 60 |
% Equals \= Greater than \> Question mark \? |
| 61 |
% Commercial at \@ Left bracket \[ Backslash \\ |
| 62 |
% Right bracket \] Circumflex \^ Underscore \_ |
| 63 |
% Grave accent \` Left brace \{ Vertical bar \| |
| 64 |
% Right brace \} Tilde \~} |
| 65 |
% |
| 66 |
% |
| 67 |
% \changes{v1.0}{2010/09/21}{Initial version} |
| 68 |
% |
| 69 |
% \GetFileInfo{spot.sty} |
| 70 |
% |
| 71 |
% \DoNotIndex{\newcommand,\newenvironment,\def} |
| 72 |
% |
| 73 |
% |
| 74 |
% \title{The \textsf{spot} package: \\ |
| 75 |
% spotlight highlighting for Beamer\thanks{This document |
| 76 |
% corresponds to \textsf{spotlight}~\fileversion, dated \filedate.}} |
| 77 |
% \author{Anders Hendrickson\\ Concordia College, Moorhead, MN \\ \texttt{[email protected]}} |
| 78 |
% |
| 79 |
% \maketitle |
| 80 |
% |
| 81 |
% \providecommand\barg[1]{% |
| 82 |
% {\ttfamily\char`<}\meta{#1}{\ttfamily\char`>}} |
| 83 |
% \providecommand\TikZ{Ti\emph{k}Z} |
| 84 |
% |
| 85 |
% \section{Introduction} |
| 86 |
% |
| 87 |
% |
| 88 |
% Beamer's |\alert| command is designed to call the viewer's attention |
| 89 |
% to certain parts of the slide, but under some circumstances it can be less effective than desired. |
| 90 |
% First, because the actual colors produced depend on the projector |
| 91 |
% hardware used and the ambient lighting in the room, |
| 92 |
% you can find to your dismay that the color change |
| 93 |
% provided by |\alert| is barely discernible onscreen. |
| 94 |
% Of course you can fiddle with |\setbeamercolor{alerted text}|\marg{color} |
| 95 |
% to achieve better results on your own projector, |
| 96 |
% but you may still face surprises when taking your presentation to another institution. |
| 97 |
% Moreover, the |\alert| command is often ineffective at highlighting |
| 98 |
% just one or two characters on a full slide; |
| 99 |
% in such a situation, |
| 100 |
% a color change alone may not be striking enough to draw the viewer's eye. |
| 101 |
% For just such circumstances, this package provides a |\spot| command |
| 102 |
% to paint a ``spotlight'' of color painted behind the highlighted text, |
| 103 |
% as in \spot{this example.} |
| 104 |
% |
| 105 |
% |
| 106 |
% |
| 107 |
% \section{Usage}\label{sect:usage} |
| 108 |
% \subsection{General Usage} |
| 109 |
% |
| 110 |
% |
| 111 |
% \DescribeMacro{\spot} |
| 112 |
% The |\spot| command has the following syntax: |
| 113 |
% \begin{center} |
| 114 |
% |\spot|\barg{overlay spec}\parg{node name}\oarg{node options}\marg{highlighted text} |
| 115 |
% \end{center} |
| 116 |
% The first three parameters, \barg{overlay spec}, \parg{node name}, and \oarg{node options}, |
| 117 |
% are optional, |
| 118 |
% and any combination of them may be omitted, |
| 119 |
% but their order must not change. |
| 120 |
% For example, |\spot<5->[fill=red]{George}| is legal, |
| 121 |
% but entering |\spot[star](mynode){Joe}| will produce erroneous output. |
| 122 |
% |
| 123 |
% The \meta{overlay spec} should be a standard Beamer overlay specification; |
| 124 |
% for example, |
| 125 |
% |\spot<2-3>{Fred}| highlights the word ``Fred'' only on slides 2 and 3. |
| 126 |
% The actual ``spotlight'' shape is a \TikZ\ node. |
| 127 |
% If you wish to access the node |
| 128 |
% later---for example, to point an arrow at it---you |
| 129 |
% can specify a \meta{node name}. |
| 130 |
% Consider the following example: |
| 131 |
% \begin{quote} |
| 132 |
% \begin{tabular}{p{1.5in}p{3in}} |
| 133 |
% \spot*(first){We} can draw an arrow from the first word of this sentence to the \spot*(last){last}. |
| 134 |
% \tikz[remember picture, overlay]{\draw (first) to[->] (last);} |
| 135 |
% & \tt |
| 136 |
% |\spot(first){We}| can draw an arrow from the first word of this sentence to the |\spot(last){last}.| |
| 137 |
% |\tikz[remember picture, overlay]{| | \draw (first) to[->] (last);}| |
| 138 |
% \end{tabular} |
| 139 |
% \end{quote} |
| 140 |
% \dospots |
| 141 |
% |
| 142 |
% |
| 143 |
% The default behavior of |\spot| is to surround its argument with a gold-colored ellipse, |
| 144 |
% most intense at its center and fading towards the edges. |
| 145 |
% That behavior can be altered---for example, to change the shape or color---for |
| 146 |
% a specific instance of |\spot| by specifying \meta{node options}. |
| 147 |
% Consider the following example: |
| 148 |
% \begin{quote} |
| 149 |
% \begin{tabular}{p{1.5in}p{3in}} |
| 150 |
% To \spot*[fill=blue!50]{be,} |
| 151 |
% or not to |
| 152 |
% \spot*[star, star points=8]{be:} |
| 153 |
% that \spot*[ball color=red]{is} the |
| 154 |
% \spot*[path fading=east]{question.} |
| 155 |
% & \tt |
| 156 |
% To |\spot*[fill=blue!50]{be,}| |
| 157 |
% or not to |
| 158 |
% |\spot*[star, star points=8]{be:}| |
| 159 |
% that |\spot*[ball color=red]{is}| the |
| 160 |
% |\spot*[path fading=east]{question.}| |
| 161 |
% \end{tabular} |
| 162 |
% \end{quote} |
| 163 |
% \dospots |
| 164 |
% |
| 165 |
% For a complete understanding of possible \meta{node options}, |
| 166 |
% please see the PGF/\TikZ\ documentation. |
| 167 |
% Of particular note is that |path fading=none| will eliminate the fading, |
| 168 |
% causing the node to \spot*[path fading=none]{overlap} surrounding text. |
| 169 |
% To change the default behavior for subsequent calls to |\spot|, |
| 170 |
% the following commands are provided. |
| 171 |
% |
| 172 |
% \DescribeMacro{\setspotlightcolor} |
| 173 |
% \DescribeMacro{\resetspotlightcolor} |
| 174 |
% \DescribeMacro{\spotlightcolor} |
| 175 |
% The command |\setspotlightcolor|\marg{color} makes all subsequent invocations of |\spot| |
| 176 |
% use the specified \meta{color}. |
| 177 |
% The default shade of gold is named |spotlightgold|, |
| 178 |
% and may be restored with the command |\resetspotlightcolor|. |
| 179 |
% The current color is saved in the macro |\spotlightcolor|, |
| 180 |
% making commands such as |\setspotlightcolor{\spotlightcolor!50}| possible. |
| 181 |
% Note that if |fill=|\meta{color} is given in the \meta{node options} |
| 182 |
% or with |\setspotlightstyle|, |
| 183 |
% it takes precedence over the \meta{color} in |\spotlightcolor|. |
| 184 |
% |
| 185 |
% \DescribeMacro{\setspotlightstyle} |
| 186 |
% \DescribeMacro{\resetspotlightstyle} |
| 187 |
% \DescribeMacro{\spotlightnodeoptions} |
| 188 |
% The command |\setspotlightstyle|\marg{node options} adds \meta{node options} |
| 189 |
% to the nodes produced by all subsequent invocations of |\spot|. |
| 190 |
% The effect of multiple calls is cumulative. |
| 191 |
% Default options may be restored by |
| 192 |
% |\resetspotlightstyle|. |
| 193 |
% The current options are saved in the macro |\spotlightnodeoptions|. |
| 194 |
% |
| 195 |
% \begin{quote} |
| 196 |
% \begin{tabular}{p{1.5in}p{3in}} |
| 197 |
% & |\setspotlightcolor{red!50}| \\ |
| 198 |
% & |\spot{A} \quad| \\ |
| 199 |
% & |\setspotlightstyle{star, fill=green!50}| \\ |
| 200 |
% & |\spot{B} \quad| \\ |
| 201 |
% \setspotlightcolor{red!50} |
| 202 |
% \spot*{A} \quad |
| 203 |
% \setspotlightstyle{star, fill=green!50} |
| 204 |
% \spot*{B} \quad |
| 205 |
% \setspotlightstyle{star points=7} |
| 206 |
% \spot*{C} \quad |
| 207 |
% \resetspotlightstyle |
| 208 |
% \spot*{D} \quad |
| 209 |
% \resetspotlightcolor |
| 210 |
% \spot*{E} |
| 211 |
% & |\setspotlightstyle{star points=7}| \\ |
| 212 |
% & |\spot{C} \quad| \\ |
| 213 |
% & |\resetspotlightstyle \spot{D} \quad| \\ |
| 214 |
% & |\resetspotlightcolor \spot{E}| \\ |
| 215 |
% \end{tabular} |
| 216 |
% \end{quote} |
| 217 |
% \resetspotlightcolor |
| 218 |
% \dospots |
| 219 |
% |
| 220 |
% \subsection{Non-Beamer Usage}\label{sect:nonbeamerusage} |
| 221 |
% |
| 222 |
% Although the |spot| package is chiefly designed for use with Beamer, |
| 223 |
% it may also be used in documents |
| 224 |
% of other classes. |
| 225 |
% There are two peculiarities,\label{page:2pec} |
| 226 |
% however, the reasons for which will be explained in section \ref{sect:strategy}. |
| 227 |
% \DescribeMacro{\spot*} |
| 228 |
% First, if |\spot| is used within a |\parbox|, |
| 229 |
% a |minipage| environment, |
| 230 |
% a header or footer, |
| 231 |
% or a |p| column in a |tabular| environment, |
| 232 |
% the error message |
| 233 |
% ``|LaTeX Error: Float(s) lost|'' will result. |
| 234 |
% The remedy is to use the the starred version |\spot*| instead, |
| 235 |
% and to follow the instructions in the following paragraph. |
| 236 |
% |
| 237 |
% \DescribeMacro{\dospots} |
| 238 |
% Second, if the last call to |\spot| on a page is |
| 239 |
% in math mode, in a \TeX\ inner mode (such as a |tabular| environment), |
| 240 |
% or the starred version |\spot*|, |
| 241 |
% then the command |\dospots| must be issued somewhere later on that same page, |
| 242 |
% after the math mode or |tabular| or |\parbox| has ended. |
| 243 |
% (The actual criterion is that |\dospots| must be able to call |\marginpar|, |
| 244 |
% which cannot be done in those environments.) |
| 245 |
% If the page ends before a |\dospots| is encountered, |
| 246 |
% an error message will be generated. |
| 247 |
% |
| 248 |
% \DescribeMacro{\dospotsheader} |
| 249 |
% \DescribeMacro{\dospotsfooter} |
| 250 |
% Remembering to place a |\dospots| after each problematic |\spot| |
| 251 |
% can be a hassle. |
| 252 |
% The best solution is to use the |fancyhdr| package |
| 253 |
% to place the command |\dospotsheader| |
| 254 |
% or its synonym |\dospotsfooter| |
| 255 |
% into a header or footer appearing on every page, |
| 256 |
% obviating the need for any manual |\dospots|. |
| 257 |
% Moreover, if a spotlight is desired \emph{within} a header, footer, or marginpar, |
| 258 |
% |\spot*| should be used and |\dospotsheader| or |\dospotsfooter| should follow. |
| 259 |
% |
| 260 |
% |
| 261 |
% |
| 262 |
% |
| 263 |
% \section{Strategy}\label{sect:strategy} |
| 264 |
% \VerbatimFootnotes |
| 265 |
% This section describes the mechanism |spot| uses to draw its spotlights. |
| 266 |
% It would be simple enough to wrap the |
| 267 |
% \makeatletter |
| 268 |
% \tikz[baseline]{ |
| 269 |
% \path[use as bounding box] |
| 270 |
% node[anchor=base, inner sep=0, outer sep=0, opacity=0] |
| 271 |
% (temp) {highlighted text}; |
| 272 |
% \path (temp) |
| 273 |
% node[anchor=center, outer sep=0, |
| 274 |
% shape=ellipse, inner sep=0.5ex, |
| 275 |
% fill=\spotlightcolor, path fading=spot@fade] {highlighted text}; |
| 276 |
% } |
| 277 |
% \makeatother |
| 278 |
% within a \TikZ\ node, keeping it in line with its surroundings, |
| 279 |
% but the result is not perfect. The preceding highlighting\footnote{Produced with |
| 280 |
% \begin{verbatim} |
| 281 |
% \tikz[baseline]{ |
| 282 |
% \path[use as bounding box] |
| 283 |
% node[anchor=base, inner sep=0, outer sep=0, opacity=0] |
| 284 |
% (temp) {highlighted text}; |
| 285 |
% \path (temp) |
| 286 |
% node[anchor=center, outer sep=0, |
| 287 |
% shape=ellipse, inner sep=0.5ex, |
| 288 |
% fill=\spotlightcolor, path fading=spot@fade] {highlighted text};} |
| 289 |
% \end{verbatim} |
| 290 |
% } |
| 291 |
% was painted over previous text |
| 292 |
% but under subsequent text, creating both an uneven effect |
| 293 |
% and an unintentional emphasis on the beginning of the following word. |
| 294 |
% The solution is to leave a blank space in the text, |
| 295 |
% coming back once the entire frame has been typeset |
| 296 |
% to draw the text and its highlighting over their surroundings. |
| 297 |
% |
| 298 |
% Suppose then that |\spot<2>{foo}| is called in a Beamer frame. |
| 299 |
% On slide 1 of the frame, |
| 300 |
% the text |foo| is typeset as the sole node in a \TikZ\ picture, |
| 301 |
% with node options chosen so that it occupies |
| 302 |
% its place in the paragraph just like ordinary typeset text. |
| 303 |
% The node is given a name such as |spot@vii|, |
| 304 |
% and the |remember picture| option is used. |
| 305 |
% |
| 306 |
% When slide 2 is typeset, |
| 307 |
% the node |spot@vii| is drawn as before, except with |opacity=0| so that it is transparent. |
| 308 |
% After the contents of the entire slide are typeset, |
| 309 |
% another \TikZ\ picture uses the |overlay| option |
| 310 |
% to return to the location of |spot@vii| |
| 311 |
% and typeset |foo| in a node with |
| 312 |
% a suitably eye-catching shape, |fill| color, and fading. |
| 313 |
% |
| 314 |
% In Beamer, the code to paint the highlighted node is attached to |\end{frame}|. |
| 315 |
% The challenge for implementing |spot| in classes other than Beamer |
| 316 |
% is the lack of a hook for the end of a page; |
| 317 |
% even the |afterpage| package cannot return to the previous page to typeset new material. |
| 318 |
% The solution used is to insert the |\spot@paintspot| macro |
| 319 |
% into a |\marginpar|. |
| 320 |
% This is the source of the two peculiarities mentioned on page \pageref{page:2pec}, |
| 321 |
% for under certain circumstances, \LaTeX\ cannot process a |\marginpar| |
| 322 |
% correctly. |
| 323 |
% These circumstances include \TeX's inner vertical mode, display math, and |\parbox|es. |
| 324 |
% In these situations |
| 325 |
% |spot| must save its painting commands for later. |
| 326 |
% The command |\dospots|, called from a ``safe'' location, |
| 327 |
% inserts those saved commands into a |\marginpar|. |
| 328 |
% The alternative commands |\dospotsheader| and |\dospotsfooter| |
| 329 |
% execute the saved paint commands immediately, |
| 330 |
% making them suitable for inclusion in a header or footer. |
| 331 |
% Because this second mechanism, though more reliable, |
| 332 |
% places an extra burden on the user, |
| 333 |
% it was not chosen as the default behavior for |\spot|. |
| 334 |
% |
| 335 |
% The starred version |\spot*| uses the second mechanism in place of the first. |
| 336 |
% Moreover, the |\spot| macro will also switch to the second mechanism |
| 337 |
% when it can detect the necessity. |
| 338 |
% If |\ifinner| is true, then |\marginpar| would fail; |
| 339 |
% likewise if |\ifmmode| is true, then \LaTeX\ might well be in display math mode |
| 340 |
% where |\marginpar| fails; |
| 341 |
% in these situations, |\spot| acts like |\spot*|. |
| 342 |
% Unfortunately, if |\spot| is called within a |\parbox|, |
| 343 |
% there is no test that can make |\spot| aware of that fact, |
| 344 |
% and the user will see |
| 345 |
% |LaTeX Error: Float(s) lost.| |
| 346 |
% This warning is an indication that even \LaTeX\ itself could not tell in advance |
| 347 |
% whether |\marginpar| would work properly or not. |
| 348 |
% |
| 349 |
% |
| 350 |
% |
| 351 |
% \section{Limitations and Tips} |
| 352 |
% \begin{itemize} |
| 353 |
% |
| 354 |
% \item Because |\spot{foo}| places the text |foo| in a \TikZ\ node, |
| 355 |
% it will not allow line breaks within |foo|. |
| 356 |
% For highlighting that permits automatic line breaking, consider the |\hl| command of the |soul| package. |
| 357 |
% |
| 358 |
% \item The |\spot| command does not work well in a Beamer frame |
| 359 |
% broken into multiple slides by |allowframebreaks|. |
| 360 |
% |
| 361 |
% \item In non-Beamer class, spotlights meant for the bottom of one page |
| 362 |
% may sometimes show up at the bottom of the next page. |
| 363 |
% |
| 364 |
% |
| 365 |
% |
| 366 |
% \item It is possible to call |\spot| in math mode, |
| 367 |
% but as the argument will be set in a box within a \TikZ\ node, |
| 368 |
% the results may need tinkering. |
| 369 |
% For example, |$a^{\spot{b}}$| produces $a^{\spot{b}}$, |
| 370 |
% not $a^{\spot{\scriptstyle b}}$; |
| 371 |
% to make the superscript the correct size, |
| 372 |
% you must write |$a^{\spot{\scriptstyle b}}$|. |
| 373 |
% Likewise to produce $a\mathbin{\spot{=}}b$ requires writing |
| 374 |
% |$a\mathbin{\spot{=}}b$|, since merely writing |
| 375 |
% |$a\spot{=}b$| produces the poorly spaced $a\spot{=}b$. |
| 376 |
% \dospots |
| 377 |
% |
| 378 |
% \item As mentioned in section \ref{sect:nonbeamerusage}, |
| 379 |
% when using |spot| in a document class other than Beamer, |
| 380 |
% it is best to include |\dospotsheader| in a header appearing on every page. |
| 381 |
% A minimal solution is to put the following in the preamble: |
| 382 |
% \begin{verbatim} |
| 383 |
% \usepackage{fancyhdr} |
| 384 |
% \pagestyle{fancy} |
| 385 |
% \fancyhf{} |
| 386 |
% \rhead{\dospotsheader} |
| 387 |
% \end{verbatim} |
| 388 |
% \end{itemize} |
| 389 |
% |
| 390 |
% |
| 391 |
% \StopEventually{} |
| 392 |
% |
| 393 |
% \section{Implementation} |
| 394 |
% |
| 395 |
% \subsection{Packages and Hooks} |
| 396 |
% |
| 397 |
% The \TikZ\ package must be loaded with the necessary libraries. |
| 398 |
% \begin{macrocode} |
| 399 |
\RequirePackage{tikz} |
| 400 |
\usetikzlibrary{shapes} |
| 401 |
\usetikzlibrary{fadings} |
| 402 |
% \end{macrocode} |
| 403 |
% |
| 404 |
% We next check whether we are in the Beamer class |
| 405 |
% or not, and we abbreviate |\expandafter| in the usual way. |
| 406 |
% \begin{macrocode} |
| 407 |
\newif\ifspot@beamer |
| 408 |
\@ifundefined{beamer@frameslide}{\spot@beamerfalse}{\spot@beamertrue} |
| 409 |
\let\xa=\expandafter |
| 410 |
% \end{macrocode} |
| 411 |
% |
| 412 |
% In Beamer, we will need hooks for running code at the beginning and end of each frame. |
| 413 |
% The commands |\AtEveryBeginFrame| and |\AtEveryEndFrame| store commands to be run in every frame, |
| 414 |
% \changes{v1.1}{2011/05/09}{Fixed bug with Beamer's title command} |
| 415 |
% while the command |\AtEndFrame| applies only to the current frame. |
| 416 |
% We repeat the last token of |\beamer@frameslide|, namely |\beamer@checkframetitle|, |
| 417 |
% so that |\beamer@frameslide| can still detect the presence of a frame title. |
| 418 |
% \begin{macrocode} |
| 419 |
\ifspot@beamer |
| 420 |
\g@addto@macro\beamer@frameslide{\spot@everybeginframe@hook\beamer@checkframetitle} |
| 421 |
% \end{macrocode} |
| 422 |
% Whereas |\g@addto@macro| makes it easy to add |
| 423 |
% |\spot@everybeginframe@hook| to the end of the |\begin{beamer@frameslide}| code, |
| 424 |
% adding hooks to be executed right \emph{before} |
| 425 |
% the existing |\end{beamer@frameslide}| code is a little more involved. |
| 426 |
% \begin{macrocode} |
| 427 |
\let\spot@oldmaterial=\endbeamer@frameslide |
| 428 |
\def\spot@newmaterial{% |
| 429 |
\spot@endframe@hook% |
| 430 |
\gdef\spot@endframe@hook{}% |
| 431 |
\spot@everyendframe@hook} |
| 432 |
\xa\xa\xa\def |
| 433 |
\xa\xa\xa\endbeamer@frameslide |
| 434 |
\xa\xa\xa{% |
| 435 |
\xa\spot@newmaterial\spot@oldmaterial}% |
| 436 |
% \end{macrocode} |
| 437 |
% Having placed hooks into the |beamer@frameslide| environment, |
| 438 |
% we now initialize those hooks as empty |
| 439 |
% and create the commands |\AtEndFrame|, |\AtEveryEndFrame|, and |\AtEveryBeginFrame|. |
| 440 |
% \begin{macrocode} |
| 441 |
\def\spot@endframe@hook{} |
| 442 |
\def\spot@everyendframe@hook{} |
| 443 |
\def\spot@everybeginframe@hook{} |
| 444 |
\long\def\AtEndFrame#1{\g@addto@macro\spot@endframe@hook{#1}} |
| 445 |
\long\def\AtEveryEndFrame#1{\g@addto@macro\spot@everyendframe@hook{#1}} |
| 446 |
\long\def\AtEveryBeginFrame#1{\g@addto@macro\spot@everybeginframe@hook{#1}} |
| 447 |
% \end{macrocode} |
| 448 |
% In classes other than Beamer, we will need the |afterpage| package to run code between pages. |
| 449 |
% \begin{macrocode} |
| 450 |
\else |
| 451 |
\RequirePackage{afterpage} |
| 452 |
\fi |
| 453 |
% \end{macrocode} |
| 454 |
% |
| 455 |
% |
| 456 |
% |
| 457 |
% \subsection{Spotlight options} |
| 458 |
% We next define the options. |
| 459 |
% The |\spotlightcolor| macro stores the working color; |
| 460 |
% it can be edited with the commands |\setspotlightcolor| and |\resetspotlightcolor|. |
| 461 |
% \begin{macrocode} |
| 462 |
\def\spotlightcolor{spotlightgold} |
| 463 |
\def\setspotlightcolor#1{\xdef\spotlightcolor{#1}} |
| 464 |
\def\resetspotlightcolor{\gdef\spotlightcolor{spotlightgold}} |
| 465 |
% \end{macrocode} |
| 466 |
% Likewise the command |\spotlightnodeoptions| stores additional node options chosen by the user. |
| 467 |
% The command |\setspotlightstyle| adds to it, and |\resetspotlightstyle| empties it. |
| 468 |
% \begin{macrocode} |
| 469 |
\def\spotlightnodeoptions{} |
| 470 |
\def\setspotlightstyle#1{\g@addto@macro\spotlightnodeoptions{#1, }} |
| 471 |
\def\resetspotlightstyle{\gdef\spotlightnodeoptions{}} |
| 472 |
% \end{macrocode} |
| 473 |
% Finally, here are the default color and fading. |
| 474 |
% \begin{macrocode} |
| 475 |
\definecolor{spotlightgold}{RGB}{255,204,51} |
| 476 |
\tikzfading[name=spot@fade, |
| 477 |
inner color=transparent!0, |
| 478 |
outer color=transparent!60] |
| 479 |
% \end{macrocode} |
| 480 |
% The count register |\c@spot@spots| numbers each spotlight on the frame or page. |
| 481 |
% \begin{macrocode} |
| 482 |
\newcount\c@spot@spots |
| 483 |
\c@spot@spots=1 |
| 484 |
\ifspot@beamer |
| 485 |
\AtEveryBeginFrame{\global\c@spot@spots=1\relax} |
| 486 |
\else |
| 487 |
\afterpage{\global\c@spot@spots=1\relax} |
| 488 |
\fi |
| 489 |
% \end{macrocode} |
| 490 |
% |
| 491 |
% |
| 492 |
% |
| 493 |
% |
| 494 |
% \subsection{Input parsing} |
| 495 |
% \begin{macro}{\spot} |
| 496 |
% The macro |\spot| comes in starred and unstarred versions. |
| 497 |
% We first check for the presence of the star, |
| 498 |
% and set a flag if it is present. |
| 499 |
% \begin{macrocode} |
| 500 |
\newif\ifspot@star |
| 501 |
\spot@starfalse |
| 502 |
\def\spot{\@ifnextchar*{\spot@star}{\spot@nostar}} |
| 503 |
\def\spot@star#1{\global\spot@startrue\spot@nostar} |
| 504 |
% \end{macrocode} |
| 505 |
% \end{macro} |
| 506 |
% \begin{macro}{\spot@nostar} |
| 507 |
% As described in section \ref{sect:usage}, |
| 508 |
% the full syntax of |\spot| is |
| 509 |
% \begin{center} |
| 510 |
% |\spot|\barg{overlay spec}\parg{node name}\oarg{node options}\marg{highlighted text} |
| 511 |
% \end{center} |
| 512 |
% with each of \meta{overlay spec}, \meta{node name}, and \meta{node options} being optional. |
| 513 |
% If any is not specified, we fill in the appropriate default value. |
| 514 |
% |
| 515 |
% The default overlay specification is |<1->|. |
| 516 |
% \begin{macrocode} |
| 517 |
\def\spot@nostar{% |
| 518 |
\@ifnextchar<{\spot@in}{\spot@in<1->}% |
| 519 |
} |
| 520 |
% \end{macrocode} |
| 521 |
% \end{macro} |
| 522 |
% \begin{macro}{\spot@in} |
| 523 |
% The default \meta{node name} is |spot@dummynode|. |
| 524 |
% \begin{macrocode} |
| 525 |
\def\spot@in<#1>{% |
| 526 |
\@ifnextchar({\spot@inte<#1>}% |
| 527 |
{\spot@inte<#1>(spot@dummynode)}% |
| 528 |
} |
| 529 |
% \end{macrocode} |
| 530 |
% \end{macro} |
| 531 |
% \begin{macro}{\spot@inte} |
| 532 |
% The default is to have no extra \meta{node options}. |
| 533 |
% \begin{macrocode} |
| 534 |
\def\spot@inte<#1>(#2){% |
| 535 |
\@ifnextchar[{\spot@intern<#1>(#2)}{\spot@intern<#1>(#2)[]}% |
| 536 |
} |
| 537 |
% \end{macrocode} |
| 538 |
% \end{macro} |
| 539 |
% \begin{macro}{\spot@intern} |
| 540 |
% Because the spotlight is painted after the rest of the page is drawn, |
| 541 |
% it is important to expand the node options now |
| 542 |
% (including |\spotlightcolor| and the user-defined |\spotlightnodeoptions|), |
| 543 |
% so that they will not be affected by redefinitions later on the page. |
| 544 |
% Note that the order of parameters is changed to make the |\expandafter|s work. |
| 545 |
% \begin{macrocode} |
| 546 |
\def\spot@intern<#1>(#2)[#3]#4{% |
| 547 |
\edef\spot@totaloptions{fill=\spotlightcolor, \spotlightnodeoptions, #3}% |
| 548 |
\xa\spot@internal\xa[\spot@totaloptions]<#1>(#2){#4}% |
| 549 |
} |
| 550 |
% \end{macrocode} |
| 551 |
% \end{macro} |
| 552 |
% \begin{macro}{\spot@internal} |
| 553 |
% Finally, we are ready to call the macros which actually do the work, |
| 554 |
% depending on whether we are running Beamer or some other class. |
| 555 |
% We return the parameters to their normal order. |
| 556 |
% \begin{macrocode} |
| 557 |
\def\spot@internal[#1]<#2>(#3)#4{% |
| 558 |
\ifspot@beamer% |
| 559 |
\spot@internal@beamer<#2>(#3)[#1]{#4}% |
| 560 |
\else% |
| 561 |
\spot@internal@static<#2>(#3)[#1]{#4}% |
| 562 |
\fi% |
| 563 |
} |
| 564 |
% \end{macrocode} |
| 565 |
% \end{macro} |
| 566 |
% |
| 567 |
% |
| 568 |
% |
| 569 |
% |
| 570 |
% |
| 571 |
% |
| 572 |
% |
| 573 |
% |
| 574 |
% |
| 575 |
% \subsection{Beamer version} |
| 576 |
% |
| 577 |
% \begin{macro}{\spot@internal@beamer} |
| 578 |
% The macro |\spot@internal@beamer| |
| 579 |
% implements the |\spot| command when used in a Beamer presentation. |
| 580 |
% \begin{macrocode} |
| 581 |
\def\spot@internal@beamer<#1>(#2)[#3]#4{% |
| 582 |
% \end{macrocode} |
| 583 |
% The text to be highlighted is first saved in a box named something like |\spot@box@vii|, |
| 584 |
% where the roman numeral represents the spot counter |\c@spot@spots|. |
| 585 |
% In this way it will automatically have the correct font size and shape (italics, boldface, etc.). |
| 586 |
% It is set in math mode if necessary. |
| 587 |
% For the sake of readability of the code, |\spot@currentbox| is let equal to |\spot@box@vii|. |
| 588 |
% \begin{macrocode} |
| 589 |
\@ifundefined{spot@box@\romannumeral\c@spot@spots}% |
| 590 |
{\xa\newbox\csname spot@box@\romannumeral\c@spot@spots\endcsname}{}% |
| 591 |
\ifmmode |
| 592 |
\global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{$#4$}% |
| 593 |
\else |
| 594 |
\global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{#4}% |
| 595 |
\fi |
| 596 |
\xa\let\xa\spot@currentbox\csname spot@box@\romannumeral\c@spot@spots\endcsname% |
| 597 |
% \end{macrocode} |
| 598 |
% Now we are ready to set the text. |
| 599 |
% On the highlighted slides, we actually produce two \TikZ\ nodes at this time. |
| 600 |
% The first is merely a transparent copy of the text itself; |
| 601 |
% the second is a transparent copy of the entire highlighted node shape, |
| 602 |
% and receives the \meta{node name} called by the user. |
| 603 |
% We require the first node (with the |use as bounding box| option) |
| 604 |
% so as to fit the text seamlessly in line with its surroundings. |
| 605 |
% The second node, bearing \meta{node name}, must be drawn now, so that the user can |
| 606 |
% refer to \meta{node name} |
| 607 |
% within the frame; |
| 608 |
% the \meta{node name} could not simply be attached to the visible spotlight, |
| 609 |
% since that is drawn with |\AfterEndFrame|, \emph{after} all the user's code has been processed. |
| 610 |
% On unhighlighted slides, we simply draw an opaque copy of the text in a \TikZ\ node. |
| 611 |
% \begin{macrocode} |
| 612 |
\tikz[remember picture, baseline]{ |
| 613 |
\alt<#1>{\path[use as bounding box] |
| 614 |
node[anchor=base, inner sep=0, outer sep=0, opacity=0] |
| 615 |
(spot@\romannumeral\c@spot@spots) {\usebox\spot@currentbox}; |
| 616 |
\path (spot@\romannumeral\c@spot@spots) |
| 617 |
node[anchor=center, outer sep=0, |
| 618 |
shape=ellipse, inner sep=0.5ex, |
| 619 |
#3, opacity=0] (#2) {\usebox\spot@currentbox};} |
| 620 |
{\path node[anchor=base, inner sep=0, outer sep=0, opacity=1] |
| 621 |
(#2) {\usebox\spot@currentbox};} |
| 622 |
}% |
| 623 |
% \end{macrocode} |
| 624 |
% Finally, we save the information needed to paint the spotlight at the end of the slide. |
| 625 |
% Sometimes calling |\AtEndFrame| |
| 626 |
% adds a little extra height to the frame's contents, |
| 627 |
% which could cause a slight movement of the frame between highlighted and unhighlighted slides. |
| 628 |
% We therefore make a call to |\AtEndFrame| on unhighlighted slides |
| 629 |
% as well, to ensure that the same extra height be added |
| 630 |
% even when we're not painting spotlights. |
| 631 |
% \begin{macrocode} |
| 632 |
\alt<#1>{\xa\spot@savepaint\xa{\romannumeral\c@spot@spots}[#3]}% |
| 633 |
{\AtEndFrame{\rule{0pt}{0pt}}}% |
| 634 |
% \end{macrocode} |
| 635 |
% Finally, we increment the counter |\c@spot@spots| and end the macro. |
| 636 |
% \begin{macrocode} |
| 637 |
\global\advance\c@spot@spots by 1\relax% |
| 638 |
} |
| 639 |
% \end{macrocode} |
| 640 |
% \end{macro} |
| 641 |
% \begin{macro}{\spot@savepaint} |
| 642 |
% The following macro saves the actual spotlight-drawing command to be executed at the end of the slide. |
| 643 |
% The first parameter is a roman numeral labeling the spotlight, |
| 644 |
% while the second contains the node options. |
| 645 |
% \begin{macrocode} |
| 646 |
\def\spot@savepaint#1[#2]{% |
| 647 |
\AtEndFrame{\spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}% |
| 648 |
} |
| 649 |
% \end{macrocode} |
| 650 |
% \end{macro} |
| 651 |
% \begin{macro}{\spot@paintspot} |
| 652 |
% The command |\spot@paintspot| actually draws the spotlight at the saved location. |
| 653 |
% Note that the first parameter is not the user-specified \meta{node name}, |
| 654 |
% but an automatically generated name such as |spot@vii|. |
| 655 |
% \begin{macrocode} |
| 656 |
\def\spot@paintspot(#1)[#2]#3{% |
| 657 |
\begin{tikzpicture}[remember picture, overlay, baseline] |
| 658 |
\path (#1) node[anchor=center, outer sep=0, |
| 659 |
shape=ellipse, inner sep=0.5ex, text opacity=1, |
| 660 |
path fading=spot@fade, text=black, #2] {#3}; |
| 661 |
\end{tikzpicture}% |
| 662 |
} |
| 663 |
% \end{macrocode} |
| 664 |
% \end{macro} |
| 665 |
% |
| 666 |
% |
| 667 |
% |
| 668 |
% \subsection{non-Beamer version} |
| 669 |
% To make the spotlight turn out correctly, |
| 670 |
% it is vital to run |\spot@paintspot| \emph{after} all surrounding text has been typeset. |
| 671 |
% Whereas in Beamer the code can be attached to |
| 672 |
% a hook in the |\end{frame}|, |
| 673 |
% in other document classes |
| 674 |
% we place the code in a |\marginpar|, |
| 675 |
% which (being a \TeX\ insertion) is typeset after the rest of the page. |
| 676 |
% If |\spot| is called in certain \TeX\ modes, however, |
| 677 |
% |\marginpar| would produce an error. |
| 678 |
% In this case, |\spot| saves up the commands to be placed into a |\marginpar| later. |
| 679 |
% \begin{macro}{\spot@savedpaintcommands} |
| 680 |
% \begin{macro}{\dospots} |
| 681 |
% Whenever |\spot| is called, the |\spot@paintspot| commands |
| 682 |
% will be saved up in the macro |\spot@savedpaintcommands|. |
| 683 |
% A subsequent call to |\dospots|, by the user if necessary, |
| 684 |
% executes those commands and resets the macro to empty. |
| 685 |
% \begin{macrocode} |
| 686 |
\gdef\spot@savedpaintcommands{} |
| 687 |
\def\dospots{% |
| 688 |
\marginpar{\spot@savedpaintcommands}% |
| 689 |
\gdef\spot@savedpaintcommands{}% |
| 690 |
} |
| 691 |
% \end{macrocode} |
| 692 |
% \end{macro} |
| 693 |
% \end{macro} |
| 694 |
% \begin{macro}{\dospotsheader} |
| 695 |
% \begin{macro}{\dospotsfooter} |
| 696 |
% Since headers and footers are also \TeX\ insertions, |
| 697 |
% the |\spot@savedpaintcommands| could also be run there. |
| 698 |
% The following commands are synonyms. |
| 699 |
% \begin{macrocode} |
| 700 |
\def\dospotsheader{% |
| 701 |
\spot@savedpaintcommands% |
| 702 |
\gdef\spot@savedpaintcommands{}% |
| 703 |
} |
| 704 |
\let\dospotsfooter=\dospotsheader |
| 705 |
% \end{macrocode} |
| 706 |
% \end{macro} |
| 707 |
% \end{macro} |
| 708 |
% \begin{macro}{\spot@internal@static} |
| 709 |
% Much of the code in |\spot@internal@static| is identical with that of |\spot@internal|. |
| 710 |
% The chief difference is that the overlay specification is completely ignored. |
| 711 |
% \begin{macrocode} |
| 712 |
\def\spot@internal@static<#1>(#2)[#3]#4{% |
| 713 |
\@ifundefined{spot@box@\romannumeral\c@spot@spots}% |
| 714 |
{\xa\newbox\csname spot@box@\romannumeral\c@spot@spots\endcsname}{}% |
| 715 |
\ifmmode |
| 716 |
\global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{$#4$}% |
| 717 |
\else |
| 718 |
\global\xa\setbox\csname spot@box@\romannumeral\c@spot@spots\endcsname=\hbox{#4}% |
| 719 |
\fi |
| 720 |
\xa\let\xa\spot@currentbox\csname spot@box@\romannumeral\c@spot@spots\endcsname% |
| 721 |
\tikz[remember picture, baseline]{ |
| 722 |
\path[use as bounding box] |
| 723 |
node[anchor=base, inner sep=0, outer sep=0, opacity=0] |
| 724 |
(spot@\romannumeral\c@spot@spots) {\usebox\spot@currentbox}; |
| 725 |
\path (spot@\romannumeral\c@spot@spots) |
| 726 |
node[anchor=center, inner sep=0, outer sep=0, |
| 727 |
shape=ellipse, inner sep=0.5ex, |
| 728 |
#3, opacity=0] (#2) {\usebox\spot@currentbox}; |
| 729 |
}% |
| 730 |
\xa\spot@static@savepaint\xa{\romannumeral\c@spot@spots}[#3]% |
| 731 |
\global\advance\c@spot@spots by 1\relax% |
| 732 |
\global\spot@starfalse% |
| 733 |
} |
| 734 |
% \end{macrocode} |
| 735 |
% \end{macro} |
| 736 |
% \begin{macro}{\spot@static@savepaint} |
| 737 |
% When |\spot@static@savepaint| is called, it first checks whether \TeX\ is in |
| 738 |
% an inner mode and/or math mode, and whether the starred version |spot*| was used. |
| 739 |
% If any of these three conditions holds, a call to |\marginpar| would likely fail, |
| 740 |
% so the |\marginpar| command is saved to be executed by a |\dospots| command sometime later, |
| 741 |
% and |\spot@checkforlostspots| will be run after the current page is processed. |
| 742 |
% Otherwise, |
| 743 |
% the appropriate |\spot@paintspot| command is immediately placed in a |\marginpar|, |
| 744 |
% and any saved |\marginpar| commands are run at this time with |\dospots|. |
| 745 |
% As with |\spot@savepaint|, the first parameter is |
| 746 |
% the roman numeral identifying which spotlight is being painted, |
| 747 |
% and the second contains the node options. |
| 748 |
% \begin{macrocode} |
| 749 |
\def\spot@static@savepaint#1[#2]{% |
| 750 |
\def\spot@saveit{% |
| 751 |
\g@addto@macro\spot@savedpaintcommands{% |
| 752 |
\spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}% |
| 753 |
\afterpage{\spot@checkforlostspots}% |
| 754 |
}% |
| 755 |
\ifspot@star |
| 756 |
\spot@saveit |
| 757 |
\else |
| 758 |
\ifinner |
| 759 |
\spot@saveit |
| 760 |
\else |
| 761 |
\ifmmode |
| 762 |
\spot@saveit |
| 763 |
\else |
| 764 |
\marginpar{\spot@paintspot(spot@#1)[#2]{\usebox{\csname spot@box@#1\endcsname}}}% |
| 765 |
\dospots |
| 766 |
\fi |
| 767 |
\fi |
| 768 |
\fi |
| 769 |
} |
| 770 |
% \end{macrocode} |
| 771 |
% \end{macro} |
| 772 |
% \begin{macro}{\spot@checkforlostspots} |
| 773 |
% Between pages, the command |\spot@checkforlostspots| checks whether any |
| 774 |
% |\spot@paintspot| commands were saved into |\spot@savedpaintcommands| but never |
| 775 |
% executed by a |\dospots|. If so, it issues an error message to the user. |
| 776 |
% \begin{macrocode} |
| 777 |
\def\spot@checkforlostspots{% |
| 778 |
\def\spot@empty{}% |
| 779 |
\ifx\spot@savedpaintcommands\spot@empty% |
| 780 |
\relax% |
| 781 |
\else% |
| 782 |
\bgroup |
| 783 |
\advance\count0 by -1 |
| 784 |
\PackageError{spot}% |
| 785 |
{A \protect\dospots\space command is missing |
| 786 |
from page \the\count0.\MessageBreak |
| 787 |
Some highlighted text will not appear in the output}% |
| 788 |
{If the last \protect\spot\space command on a |
| 789 |
page is issued in math mode or a \MessageBreak |
| 790 |
TeX inner mode (such as a tabular environment), |
| 791 |
it must be followed by a \MessageBreak |
| 792 |
\protect\dospots\space command somewhere later |
| 793 |
on the page, outside such a mode.\MessageBreak |
| 794 |
You could also put \protect\dospotsheader\space |
| 795 |
in a header or footer on each page.} |
| 796 |
\egroup |
| 797 |
\fi% |
| 798 |
} |
| 799 |
% \end{macrocode} |
| 800 |
% \end{macro} |
| 801 |
% |
| 802 |
% |
| 803 |
% \Finale |
| 804 |
\endinput |