Debian Codegraph @

texmf-dist/source/latex/spot/spot.dtx

raw
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