Relative overlay specification in beamer?

Question

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:

1. Should the specified offset be negative or positive?
2. How should the offset be specified? The manual does not provide any examples.
3. Is the offset incremented (or perhaps) decremented before it is being applied?
4. What's the value of the beamerpauses counter within the code to which the overlay is applied?
5. 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}

Answer 1

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:

1. 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).

2. How should the offset be specified?

   • The offset should be written using the same syntax as in +, e.g., <.(1)->, <.(2)->, etc.

3. Is the offset incremented (or perhaps) decremented before it is being applied?

   • Neither. Writing <.-> is the same as writing <.(0)->.

4. 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).

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.