[Tex/LaTex] Relative overlay specification in beamer

beameroverlays

Reading the following quote from the beamer manual, I was left a bit confused:

When you write <.->, a similar thing as in <+-> happens except that the counter beamerpauses is not
incremented and except that you get the value of beamerpauses decreased by one. Thus a dot, possibly followed
by an offset, just expands to the current value of the counter beamerpauses minus one, possibly offset.

I had difficulties in parsing the last sentence, and I found that I cannot answer any of the following questions:

Should the specified offset be negative or positive?
How should the offset be specified? The manual does not provide any examples.
Is the offset incremented (or perhaps) decremented before it is being applied?
What's the value of the beamerpauses counter within the code to which the overlay is applied?
What's the value of this counter after the specification?

Minimal Non-Working Example

To understand this better, I created the following minimal example, which does not compile.

\documentclass{beamer}
\begin{document}
\newcommand\cn{{\small\emph{\textbf{Beamer pauses is \arabic{beamerpauses}}}}}

\begin{frame}[fragile]\frametitle{Dot Notation in Overlays}
  \begin{enumerate}
    \item This is my first item, no overlay specification; \cn
    \item<+-> This is my second item, overlay specification is \verb/<+->/; \cn
    \item<.-> This is my third item, overlay specification is \verb/<.->/; \cn
    \item This is my fourth item, no overlay specification; \cn
    \item<.-> This is my fifth item, overlay specification is \verb/<.->/; \cn
    \item<.(1)-> This is my sixth item, overlay specification is \verb/<.(1)->/; \cn
    \item This is my seventh item, no overlay specification; \cn
    \item<.(-1)-> This is my eighth item, overlay specification is \verb/<.(-1)->/; \cn
    \item This is my ninth item, no overlay specification; \cn
    \item<.(-2)-> This is my tenth item, overlay specification is \verb/<.(-2)->/; \cn
    \item This is my eleventh item, no overlay specification; \cn
    \item<.(+1)-> This is my twelfth item, overlay specification is \verb/<.(+1)->/; \cn
    \item This is my thirteenth item, no overlay specification; \cn
    \item<.(+2)-> This is my fourteenth item, overlay specification is \verb/<.(+2)->/; \cn
    \item This is my fifteenth and final item, with no overlay specification; \cn
  \end{enumerate}
\end{frame}
\end{document}

The error message I got was:

Runaway argument?
! File ended while scanning use of \next.
<inserted text> 
                \par 
<*> myfile.tex

?

My requests is then: can you help my compile this example, and, more importantly, explain the output in view of the general principles I failed to discover.

Minimal Working Example

The following example explains what I have discovered so far, also based on the discussion below.

\documentclass{beamer}
\usepackage{color}
  \newcommand\red[1]{\textcolor{red}{#1} }
  \newcommand\blue[1]{\textcolor{blue}{#1} }

  \makeatletter
\newcommand*{\overlaynumber}{\number\beamer@slideinframe}
\makeatother

\newcommand\noOverlay{\red{No OS---permanent} \cn}
\newcommand\plusMinus{\blue{OS is \texttt{<+->};} \cn}
\usepackage{multicol}\raggedcolumns

\newcommand\ct{\texttt{\textbackslash{}beamerpauses}}
\newcommand\cn{\hfill\textcolor{green!50!black}{\tiny\ct=\arabic{beamerpauses}}}
\begin{document}
\scriptsize
\renewcommand\baselinestretch{0.8}
\begin{frame}\frametitle{Beamer's Overlay Specification (OS) With \texttt{<.$X$>}}
  \alert{\textbf{Slide \#\overlaynumber}}
  \begin{multicols*}{2}
    \begin{enumerate}
      \item\noOverlay 
      \item<+->\plusMinus
      \item<+->\plusMinus
      \item<+->\plusMinus
      \item\noOverlay
      \item<.->OS \texttt{<.->} means \emph{present with last overlay},
    without advancing \ct; \cn
      \item\noOverlay
      \item<.(0)->OS \texttt{<.(0)->} is just the same as \texttt{<.->}; \cn
      \item<.-> in fact, all consecutive occurrences of the \texttt{<.->} OS are displayed together. \cn
      \item\noOverlay 
      \item\plusMinus
      \item<.(-1)-> OS, \texttt{<.(-1)->} means: present the overlayed 
        content \emph{\underline{two} slides before} the current value of \ct; \ct{} does not change; \cn
      \item<+->\plusMinus
      \item<+->\plusMinus
      \item<.(-2)-> OS \texttt{<.(-2)->} means: present the overlayed 
        content \emph{\underline{three} slides before} the current value of counter  \ct; as usual, the counter \ct{} does not change; \cn
      \item\noOverlay
      \item<.(1)->  OS \texttt{<.(1)->} means:
        present with \emph{current} overlay; do not advance \ct; \cn
      \item\noOverlay
      \item<.(2)->  OS \texttt{<.(2)->} means:
        present with \emph{next} overlay; do not advance \ct; \cn
      \item<.(3)->  Similarly, OS \texttt{<.(3)->} means:
        present with overlay \emph{after the next}; as usual, do not advance \ct; \cn
        \item\noOverlay
        \item<+->\plusMinus
        \item\noOverlay
        \item<+->\plusMinus
        \item<+->\plusMinus
        \item<+->\plusMinus
      \end{enumerate}
    \end{multicols*}
  \end{frame}
\end{document}

Best Answer

Before looking at how . works, I think it's worth a brief look at how + works as in an overlay specification, and to link that to a 'plain' specification containing only explicit numbers. I'll take the offsets last, as they are more complex.

For the simple case of just numbers

\begin{itemize}
  \item<1-> From the first slide
  \item<2-> From the second slide
  \item<3-> From the third slide
  ...
\end{itemize}

the idea is pretty clear: something with a overlay spec 1- appears on the first slide and any later slides, while more complex set ups (such as <1,3-5,7>) are also possible and human-readable.

In the case of +, when beamer reads an overlay spec if replaces all of the + tokens by the current value of the beamerpauses counter, then increments the counter (to apply to the next case it finds). Thus assuming there are no other overlays in the frame,

\begin{itemize}
  \item<+-> From the first slide
  \item<+-> From the second slide
  \item<+-> From the third slide
  ...
\end{itemize}

is equivalent to the previous example: the first + is replaced by 1, the second by 2 and the third by 3.

The idea of . is it allows you to have two (or more) overlay specs which will be equivalent. For example, if we wanted to do

\begin{itemize}
  \item<1-> From the first slide
  \item<1-> From the first slide
  \item<2-> From the second slide
  \item<2-> From the second slide
  ...
\end{itemize}

without hard-coding the numbers we can't just use +. Instead, we can use ., which really means 'repeat the last value of beamerpauses':

\begin{itemize}
  \item<+-> From the first slide
  \item<.-> From the first slide
  \item<+-> From the second slide
  \item<.-> From the second slide
  ...
\end{itemize}

Here, in the first line beamerpauses is 1, so the + becomes 1. In the second line, that value then gets repeated so the . is replaced by a 1. In the third line, beamerpauses is 2 (because of the + on the first line), so we end up with the same as my hard-coded case.

Notice that while the beamer manual is describing what actaully happens at a code level, thinking about . as being 'repeat the value used for the last +' is conceptually easier and is equivalent in outcome. (Substitution always uses beamerpauses, and because + increments it you have to take one back off to get . to do the correct thing.)

This then brings us to the offset business, which is quite advanced. Again, if we take a hard-coded demo first, we might have

\begin{itemize}
  \item<2-> From the second slide
  \item<3-> From the third slide
  \item<4-> From the fourth slide
  ...
\end{itemize}

which can be done 'flexibly' as

\begin{itemize}
  \item<+(1)-> From the first slide
  \item<+(1)-> From the second slide
  \item<+(1)-> From the first slide
  ...
\end{itemize}

The idea here is that the bracketed value 'adjusts' the substitution, so the + symbols here are replaced by a value 'one ahead' of what they would normally be. Notice that beamerpauses is still 'correct', so in the example above it's 1 in the first line, 2 in the second, etc.

Exactly the same then applies in the . syntax

\begin{itemize}
  \item<+-> From the first slide
  \item<.(1)-> From the second slide
  \item<.(2)-> From the third slide
  \item<+-> From the second slide
  ...
\end{itemize}

but as the last line shows, beamerpauses isn't incremented.

The idea of the bracket syntax is to allow relative offsets without fixing the absolute overlay numbers. However, it's down to you to make sure the values are sensible. In the question, the line

\item<.(-2)-> This is my tenth item, overlay specification is \verb/<.(-2)->/; \cn

leads to an error because the last + was replaced by a 1. Thus taking 2 off it gives an overlay number of -1, which is invalid. The beamer code doesn't do a sanity test so you get a low-level error: that perhaps could be corrected, but really you need to watch your offsets!

Another thing to note is is that your really don't want to have 'extra' + symbols in your overlay. For example, in the line

\item<.(+1)-> This is my twelfth item, overlay specification is \verb/<.(+1)->/; \cn

The + is replaced by the current value of beamerpauses in the normal way, so this line first gets converted to

\item<.(21)-> This is my twelfth item, overlay specification is \verb/<.(+1)->/; \cn

and then the offset is applied: slide 22! Presumably you wanted

\item<.(1)-> This is my twelfth item, overlay specification is \verb/<.(+1)->/; \cn

i.e. one slide on from the current one, so in the example in the question slide 2.

To give an example where you might want to use these offsets, imagine that you want the first and third lines of an itemize to appear together, then the second and fourth lines, but you don't want to hard-code the slide numbers.

\begin{itemize}
  \item<+-> First item  % Creates overlay 1
  \item<+-> Second item % Creates overlay 2
  \item<.(-1)-> Third item % Appears on overlay 1
  \item<.-> Fourth item % Appears on overlay 2
\end{itemize}

This only creates 2 overlays, with the two later items set to appear based on their relative relationship to the second item: the last one where + was used and so beamerpauses was altered.

As requested, answering the specific points in the question:

Should the specified offset be negative or positive?
- The offset should not include a +, and should only be negative when this keeps the value 'in range' (the absolute value of the overlay should remain positive).
How should the offset be specified?
- The offset should be written using the same syntax as in +, e.g., <.(1)->, <.(2)->, etc.
Is the offset incremented (or perhaps) decremented before it is being applied?
- Neither. Writing <.-> is the same as writing <.(0)->.
What's the value of the beamerpauses counter within the code to which the overlay is applied?
- The same as it was before the overlay specification: it is (possibly) incremented only at the end of the overlay spec. (see point 5).
What's the value of this counter after the specification?
- If a + is present in the overlay spec, the value of beamerpauses is incremented by exactly one.

Related Solutions

[Tex/LaTex] How do automatic overlay specification work in beamer

The rules for the incremental overlay specification are given as:

\beamerpauses is initially set to 1
If + is encountered in an overlay specification, all occurrences of + are replaced by \beamerpauses, then \beamerpauses is incremented
If . is encountered in an overlay specification, all occurrences of . are replaced by \beamerpauses-1; \beamerpauses is not changed

It might be easier to understand if you pretend this, which as far as I can see is equivalent:

\beamerpauses is initially set to 0
If + is encountered in an overlay specification, \beamerpauses is incremented and all occurrences of + are replaced by \beamerpauses
If . is encountered in an overlay specification, all occurrences of . are replaced by \beamerpauses; \beamerpauses is not changed

If you assume as well that \alt is smart and gobbles the inactive argument rather than expands it, you would guess that

\alt<-+>{\alert<+>{foo}\alert<+>{bar}}{\alert<.>{bar}\alert<.>{foo}}

is the same as

\alt<-1>{\alert<+>{foo}\alert<+>{bar}}{\alert<.>{bar}\alert<.>{foo}}

On slide 1, the first argument \alert<+>{foo}\alert<+>{bar} is expanded, resulting in

\alert<2>{foo}\alert<2>{bar}

After slide 1, the second argument \alert<.>{bar}\alert<.>{foo} is instead expanded, resulting in

\alert<1>{bar}\alert<1>{foo}

So in total the combination is equivalent to

\alt<-1>{\alert<2>{foo}\alert<2>{bar}}{\alert<1>{bar}\alert<1>{foo}}

Put these in the same frame and you'll see they do the same thing.

The - indicates an interval, so <2-4> means "on slides 2 through 4." Without explicit endpoints the first and last slide are substituted. So the first <-+> specification is equivalent to <1-1>, which in turn is equivalent to <1>.

Slide by slide we get:

the \alt expands \alert<2>{foo}\alert<2>{bar}, which since \beamerpauses is 1 is the same as {foo}{bar}
the \alt expands \alert<1>{bar}\alert<1>{foo}, which since \beamerpauses is 2 is the same as {bar}{foo}.

Advanced incremental-overlay-specification-fu involves offsetting \beamerpauses with numbers in parentheses such as \alert<.(2)->{foo}\alert<+->{bar}, which will alert first bar then both foo and bar. This is how you can have parts of a frame (for instance, parts of tikzpictures) change dynamically without having them all in the same order as they are typeset on the frame or hard-coding their slide numbers.

Edit Yossi asked if \alt really is "smart". If you look in the source code for beamerbaseoverlay.sty you find:

%
% \alt and \altenv
%
\def\alt{\@ifnextchar<{\beamer@alt}{\beamer@alttwo}}
\long\def\beamer@alttwo#1#2{\beamer@ifnextcharospec{\beamer@altget{#1}{#2}}{#1}}
\long\def\beamer@altget#1#2<#3>{%
  \def\beamer@doifnotinframe{#2}\def\beamer@doifinframe{#1}%
  {\beamer@masterdecode{#3}}\beamer@donow}
\long\def\beamer@alt<#1>#2#3{%
  \def\beamer@doifnotinframe{#3}\def\beamer@doifinframe{#2}%
  {\beamer@masterdecode{#1}}\beamer@donow}

To me it looks the like the effect of \alt<#1>{#2}{#3} is that #2 and #3 are saved in macros which are expanded depending on whether #1 applies to the current frame. I don't understand expansion completely but I believe that when \def is scanning for parameter text it doesn't expand that text until the point of replacement (as opposed to \edef, which expands the parameter text before assigning it to #n). So yes, \alt is "smart" in the sense that conditionally included text is not expanded until it's included. I guess you could do a \tracingall to know for sure.

dangerous bend Late Edit

Couldn't help but paste in this frame I'm working on right now.

\begin{frame}[label=integral-of-x]{Example: Integral of $x$}
\begin{example}<+->
Find $\int_0^3 x\,dx$
\end{example}
\begin{solution}<+->
\action<.->{For any $n$ we have $\alert<.(5)>{\Delta x = \frac{3}{n}}$ and for each $i$ between $0$ and $n$, $\alert<.(4)>{x_i = \frac{3i}{n}}$.}
\action<+->{For each $i$, take $x_i$ to represent the function on the $i$th interval.}
\action<+->{So}
\begin{align*}
    \action<.->{\int_0^3 x\,dx = \lim_{n\to\infty} R_n }
        \action<+->{&= \lim_{n\to\infty} \sum_{i=1}^n \alert<.(1)>{f(x_i)}\,\alert<.(2)>{\Delta x}}
        \action<+->{ = \lim_{n\to\infty}\sum_{i=1}^n 
            \alert<.>{\left(\frac{\alert<.(2)>{3}i}{\alert<.(2)>{n}}\right)}
            \alert<+>{\left(\frac{\alert<.(1)>{3}}{\alert<.(1)>{n}}\right) }\\}
        \action<+->{&= \lim_{n\to\infty}\alert<.>{\frac{9}{n^2}} \alert<.(1)>{\sum_{i=1}^n i}}
        \action<+->{ = \alert<.(1)>{\lim_{n\to\infty}}\frac{9}{\alert<.(1)>{n^2}} 
            \cdot \alert<.>{\frac{\alert<.(1)>{n(n+1)}}{2}}}
        \action<+->{= \frac{9}{2}\alert<.>{\cdot 1}}
\end{align*}
\end{solution}
\end{frame}

[Tex/LaTex] Take 2: How do automatic overlay specifications work in Beamer (in a nested situation)

It's logic, captain, but not as we know it.

The crucial fact to remember is that every time beamer sees a + then beamerpauses is incremented. Here's what I see, with the value of beamerpauses (in italics) evaluated at lots of occasions. First, the actual code I ran (beamerpauses coloured to make it stand out).

{\color{green}\thebeamerpauses}
\only<1-+(3)>{\alert<-+>{foo} {\color{green}\thebeamerpauses} \alert<-+>{bar}}
{\color{green}\thebeamerpauses}
\only<+>{a}\only<+>{b}\only<+>{c}\only<+>{d}\only<+>{e}
{\color{green}\thebeamerpauses}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}
{\color{green}\thebeamerpauses}

Now, what I saw (asciified), plus my interpretation of what's going on, both as to what the code expands to (in terms of what all the overlay specifications become) and an "English translation". (Disclaimer: this is all from observed behaviour rather than looking under the bonnet or hood.)

1 foo 3 bar 4 9 1 9
```
\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<4>{a}\only<5>{b}\only<6>{c}\only<7>{d}\only<8>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}
```
The +s in the \only and \alert mean that after "foo", we've incremented twice. The \alert for "bar" increments again. Each of the \onlys for "a" &c increments again, getting up to 9 by the end of that line.

1 foo 3 bar 4 9 2 9

\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<4>{a}\only<5>{b}\only<6>{c}\only<7>{d}\only<8>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}

Same again.

1 foo 3 bar 4 9 3 9

\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<4>{a}\only<5>{b}\only<6>{c}\only<7>{d}\only<8>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}

The -+ in the foo-alert is expanded to -2 so we lose the alert on foo here.

1 foo 3 bar 4 a 9 4 9

\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<4>{a}\only<5>{b}\only<6>{c}\only<7>{d}\only<8>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}

This now happens for bar. Finally, we reach the slide where the first letter appears since the + in \only<+>{a} expands to 4.

1 2 d 7 5 7
```
\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<2>{a}\only<3>{b}\only<4>{c}\only<5>{d}\only<6>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}
```
This is where the interesting stuff happens. The initial \only<1-+(3)>{...} is expanded to \only<1-4>{...}. This means that everything inside the braces now completely disappears. This includes the two +s. So all the \only<+>{a}s and so forth now think that they appear on slides two earlier than they used to.

1 2 e 7 6 7

\only<1-4>{\alert<-2>{foo} \alert<-3>{bar}}
\only<2>{a}\only<3>{b}\only<4>{c}\only<5>{d}\only<6>{e}
\only<1>{1}\only<2>{2}\only<3>{3}\only<4>{4}\only<5>{5}\only<6>{6}

Same again.

So, in summary, the key to understanding this example is to remember that \only throws away its argument on slides where it isn't meant to be. This is extremely useful in making quite complicated stuff happen on different slides.

As for your last question: not that I know of. I once needed one, couldn't find one, and so defined one. It was a crude definition, involving a wrapper around the frametitle command so that I could add some code on every slide to increment the slide counter.

Regarding the update, I think that there are two issues here with regard to the two strange lines. The first is the + issue. I have to say that I find your assertion that it should "just work" slightly disingenuous. You have already specified an exact overlay specification (in the \alt<1-2>) so there's already something that you've had to compute by hand. There are many other ways to achieve what you want with that particular example (but I suspect that it is over simplified and that what you really want will probably be much more complicated!). Possibly the most relevant is to use the onlyenv environment because that does typeset its contents (and then throw them away). So this works:

\begin{frame}
\begin{onlyenv}<1-2>
\begin{itemize}[<+->]
\item a
\item b
\end{itemize}
\end{onlyenv}
\begin{itemize}[<+->]
\item A
\item B
\item C
\item D
\end{itemize}
\end{frame}

The second issue is actually something different, I think, and it is something that I've asked about before. Somehow, getting the beamerpauses right after an automatically unveiled list is a bit complicated. I have a command \itpause for after a list which subtracts one from beamerpauses and then does \pause - that's the simplest way I've found of getting the following to Just Work:

\begin{frame}
\begin{itemize}[<+->]
\item First item
\item Second item
\end{itemize}
\itpause
On the \alert{third} frame
\end{frame}

With \pause there, the last line appears on the fourth frame, with nothing then it appears on the second frame. I would class this as a bug; and it seems to be something to do with a difference in beamerpauses inside and outside such a list environment. To see this, compare the different behaviour of \alert<.>{} inside and outside:

\begin{frame}
\alert<.>{hello}
\begin{itemize}[<+->]
\item A \alert<.>{hello}
\item B
\item C
\item D
\end{itemize}
\alert<.>{hello}
\end{frame}