Checking over the beamer codebase

Anyone who is watching the beamer GitHub repository will notice quite a lot of checkins, starting from the beginning beamer.cls and working forward. Most of these are ‘internal’ changes, so readers might wonder what is going on.

I’ve been involved with beamer for a while, but have not really taken a good look over the code yet. Several of the entries in the issue list are quite subtle, and it’s clear that a proper tidy-up of the code is needed to sort them out. That means addressing several internal inconsistencies, but it’s also helpful for me to get the code into a form I’m used to. So there are a mix of cosmetic changes in with some real improvements in the code.

Hopefully I’ll not introduce and new issues doing this work. However, it’s not easy to avoid changing behaviour in LaTeX, especially as beamer is somewhat delicate in the first place. So if anyway is keen to help with the work, simply grabbing the development code from time to time and making sure it doesn’t break existing presentations would be very helpful!

Beamer moves to GitHub

There are lots of places one can host development of open source code. I’ve used a few over the years, but in recent times have mainly focussed on GitHub. That’s true not least because the LaTeX3 development code is held there. The one package I’m involved in that’s to-date been elsewhere has been beamer: there are lots of issues in the tracker which I didn’t want to lose. So for some time it’s been slightly orphaned on BitBucket. I’ve now (finally) been able to migrate everything using a very handy script maintained by Jeff Widman. I’m making final arrangements on the move, but the key is that new issues should to to GitHub.

Beamer overlays beyond the \visible

I wrote earlier this year about using the beamer overlay concept with relative slide specifications to produce dynamic slide structures. Another question about overlays came up recently on TeX StackExhange, but this time wanting to do something a bit different.

The ‘standard’ beamer overlay system does the same as the \visible command: makes things appear and disappear, but always keeps space for them on the slide. However, beamer also provides \only, which completely omits items not visible on a slide. So the question was how to combine this idea with the general overlay concept.

It turns out that this is all quite straight-forward if you know what to look for. The standard beamer overlay syntax, for example

\item<+->

extends to include an action type to specify what the overlay should do. That is given as a keyword and an @ before the overlay number(s). So for example

\begin{itemize}
  \item First item
  \item<only@1> Second item
  \item<only@2> Replacement second item
...

will show Second item on the first slide then replace it entirely with Replacement second item on the second slide. That approach can be combined with the idea of relative slide specs, as I talked about before, to give something like

\documentclass{beamer}
\begin{document}
   \begin{frame}
   \begin{itemize}[<+->]
      \item item 1
      \item item 2
      \item<only@+-.(2)> item 3
      \item item 4
      \item item 5
   \end{itemize}

   \end{frame}
\end{document}

to have the ‘normal’ items appear one at a time but with item 3 only on slides 3 and 4.

This doesn’t just apply to only: other keywords that work here include visible and alert. The latter tends to be seen with another syntax element: | to separate out appearance from a second action. A classic example of that is

\documentclass{beamer}

\begin{document}
   \begin{frame}
   \begin{itemize}[<+->]
      \item item 1
      \item item 2
      \item<+-|alert@+(1)> item 3
      \item item 4
      \item item 5
   \end{itemize}

   \end{frame}
\end{document}

where item 3 appears on the third slide and is highlighted on the fourth one. (Note that both + substitutions in this line use the same value for the pause counter, hence needing the (1) offset.) That’s useful even without the ‘one at a time’ effect, with for example

\documentclass{beamer}

\begin{document}
   \begin{frame}
   \begin{itemize}
      \item item 1
      \item item 2
      \item<alert@+(1)> item 3
      \item item 4
      \item item 5
   \end{itemize}

   \end{frame}
\end{document}

highlighting the item on the second slide.

A bit of imagination with this syntax can cover almost any appearance/disappearance/highlight requirement. As I said before: the key thing is not to overdo it!

The +-overlay syntax and \pause in beamer

In a recent post I looked at how to use the + syntax to create flexible overlays in beamer. The key concept of that syntax is to allow dynamic slides to be created without having to hard-code slide numbers. The classic example is to reveal a list an item at a time:

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<+-> This is on the third and all following slides
    ...
  \end{itemize}
\end{frame}

As I discussed in the earlier post, this is a very powerful way to create overlays (dynamic slides from the same frame source). However, a classic problem people have is combining this with the \pause command. For example, the following creates four slides:

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<+-> This is on the third and all following slides
    ...
  \end{itemize}
  \pause
  Text after the list
\end{frame}

Why? If you read the beamer manual, it’s all about the value of \beamerpauses, but if we skip to the key point, you should not use \pause on the same slide as <+-> (or similar).

Beyond the power of \pause: \onslide

The reason people get into trouble is I think because they imagine \pause as the best way to break ‘running text’ in a frame into overlays. However, \pause is really just the most basic way of breaking up frames and is meant just for the simplest cases

\begin{frame}
  Some content
  \pause
  Some more content
\end{frame}

The moment you introduce other dynamic behaviour, you need more control than \pause offers. Indeed, this is pretty clear in the beamer manual: what people are actually looking for is \onlside.

Unlike \pause, which only knows some basic stuff about slide numbers, \onslide works with the full power of the flexible overlay specification (indeed, an overlay specification is required). So to get text after a list, what is needed is

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<+-> This is on the third and all following slides
    ...
  \end{itemize}
  \onslide<+->
  Text after the list
\end{frame}

As we are then using the special + syntax for all of the overlays, everything is properly tied together and will give the (probably) expected result: three slides.

The beamer manual covers other more complex effects using \only, \uncover, \alt and so on, but using \onslide you can do everything you think you can do with \pause but actually have it work when using the + syntax on the slide too!

beamer development

As many readers will know, I’m a member of the two-man team in charge of maintaining the beamer class (the other team member is Vedran Miletić). Vedran and I took over looking after beamer when it was unmaintained and some important bugs cropped up: lots of people rely on it, so fixes were important. There was a question on the TeX Stackexchange site recently asking about the status of maintenance. It’s a tricky one to tackle in a Q&A, but it does make a good topic for the blog!

Vedran and I are committed to keeping beamer working, and that means fixing bugs as and when we can. At the same time, we are not likely to add much in the way of new feature: small changes over time only. There are a few reasons for that, the single biggest one of which is stability. The beamer class is very widely used, and does a lot of stuff. Making significant changes is therefore tricky, particularly as we don’t have any automated tests. The internal beamer structure contributes a bit here: it’s a complex set up, partly due to some issues in LaTeX2e (why I work on LaTeX3), partly because it has to be and partly as an ‘overhaul’ might have been useful at some stage. (It’s far too late for the latter idea now: any big change would break too many documents.)

The second issue is of course time: both Vedran and I are busy, in my case not only with ‘real life’ but also with other (La)TeX projects! Then of course there is trying to stick to what beamer does: the original design quite deliberately doesn’t do some things, so as ‘auto-flowing’ text.

If you watch the BitBucket site for beamer development, you will see changes, both to fix bugs and (slowly) add new features. That’s not about to change: small changes, ‘little and (relatively) often’, are the order of the day here. Of course, if you have a patch you really want applying, we are always happy to take a look!

The beamer slide overlay concept

There was a question recently on the TeX StackExchange site about the details of how slide overlays work in the beamer class. The question itself was about a particular input syntax, but it prompted me to think that a slightly more complete look at overlays would be useful.

A word of warning before I start: don’t overdo overlays! Having text or graphics appear or disappear on a slide can be useful but is easy to over-use. I’m going to focus on the mechanics here, but that doesn’t mean that they should be used in every beamer frame you create.

Overlay basics

Before we get into the detail of how beamer deals with overlays, I’ll first give a bit of background to what they are. The beamer class is built around the idea of frames:

\begin{frame}
  \frametitle{A title}
  % Frame content
\end{frame}

which can produce one or more slides: pages of output that will appear on the screen. These separate slides within a frame are created using overlays, which is the way the beamer manual describes the idea of having the content of individual slides varying. Overlays are ‘contained’ within a single frame: when we start a new frame, any overlays from the previous one stop applying.

The most basic way to create overlays is to explicitly set up individual items to appear on a particular slide within the frame. That’s done using the (optional) overlay argument that beamer enables for many document components: this overlay specification is given in angle brackets. The classic example is a list, where the items can be made to appear one at a time.

\begin{frame}
  \begin{itemize}
    \item<1-> This is on the first and all following slides
    \item<2-> This is on the second and all following slides
    \item<3-> This is on the third and all following slides
    ...
  \end{itemize}
\end{frame}

As you can see, the overlay specification here is simply the first slide number we want the item to be on followed by a - to indicate ‘and following slides’. We can make things more specific by giving only a single slide number, giving an ending slide number and so on.

\begin{frame}
  \begin{itemize}
    \item<1> This is on the first only
    \item<-3> This is on the first three slides
    \item<2-4,6> This is on the second to fourth slides and the sixth slide
  \end{itemize}
\end{frame}

The syntax is quite powerful, but there are at least a couple of issues. First, the slide numbers are hard-coded. That means that if I want to add something else in before the first item I’ve got to renumber everything. Secondly, I’m having to repeat myself. Luckily, beamer offers a way to address both of these concerns.

Auto-incrementing the overlay

The first tool beamer offers is the the special symbol + in overlay specifications. This is used as a place holder for the ‘current overlay’, ans is automatically incremented by the class. To see it in action, I’ll rewrite the first overlay example without any fixed numbers.

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<+-> This is on the third and all following slides
    ...
  \end{itemize}
\end{frame}

What’s happening here? Each time beamer finds an overlay specification, it automatically replaces all of the + symbols with the current overlay number. It then advances the overlay number by 1. So in the above example, the first + is replaced by a 1, the second by a 2 and the third by a 3. So we get the same behaviour as in the hard-coded case, but this time if I add another item at the start of the list I don’t have to renumber everything.

There are of course a few things to notice. The first overlay in a frame is number 1, and that’s what beamer sets the counter to at the start of each frame. To get the second item in the list to appear on slide 2, we still require an overlay specification for the first item: although I used one, I could have skipped the <1-> in the hard-coded example and nothing would have changed. The second point is that every + in an overlay specification gets replaced by the same value. We’ll see later there are places you might accidentally add a + to mean ‘advance by 1’: don’t do that!

Reducing redundancy

Using the + approach has made our overlays flexible, but I’ve still have to be repetitive. Handily, beamer helps out there too by adding an optional argument to the list which inserts an overlay specification for each line:

\begin{frame}
  \begin{itemize}[<+->]
    \item This is on the first and all following slides
    \item This is on the second and all following slides
    \item This is on the third and all following slides
    ...
  \end{itemize}
\end{frame}

Notice that this is needs to be inside the ‘normal’ [ ... ] set up for an optional argument. Applying an overlay to every item might not be exactly what you want: you can still override individual lines in the standard way.

\begin{frame}
  \begin{itemize}[<+->]
    \item This is on the first and all following slides
    \item This is on the second and all following slides
    \item This is on the third and all following slides
    \item<1-> This is on the first and all following slides
    ...
  \end{itemize}
\end{frame}

Remember not to overdo this effect: just because it’s easy to reveal every list line by line doesn’t mean you should!

Repeating the overlay number

The + syntax is powerful, but as it always increments the overlay number it doesn’t allow us to remove the hard-coded numbers from a case such as

\begin{frame}
  \begin{itemize}
    \item<1-> This is on the first and all following slides
    \item<1-> This is also on the first and all following slides
    \item<2-> This is on the second and all following slides
    \item<2-> This is also on the second and all following slides
    ...
  \end{itemize}
\end{frame}

For this case, beamer offers another special symbol: ..

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<.-> This is also on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<.-> This is also on the second and all following slides
    ...
  \end{itemize}
\end{frame}

What happens here is that . can be read as ‘repeat the overlay number of the last +‘. So the two + overlay specifications create two slides, while the two lines using . in the specification ‘pick up’ the overlay number of the preceding +. (The beamer manual describes the way this is actually done, but I suspect that’s less clear than thinking of this as a repetition!)

Depending on the exact use case, you might want to combine this with the ‘reducing repeated code’ optional argument, with <.-> as an override.

\begin{frame}
  \begin{itemize}[<+->]
    \item This is on the first and all following slides
    \item<.-> This is also on the first and all following slides
    \item This is on the second and all following slides
    \item<.-> This is also on the second and all following slides
    ...
  \end{itemize}
\end{frame}

Offsets

A combination of + and . use can be used to convert many ‘hard-coded’ overlay set ups into ‘relative’ ones, where the slide numbers are generated by beamer without you having to work them out in advance. However, there are cases it does not cover. To allow even more flexibility, beamer has the concept of an ‘offset’: and adjustment to the number that is automatically inserted. Offset values are given in parentheses after the + or . symbol they apply to, for example

\begin{frame}
  \begin{itemize}
    \item<+(1)-> This is on the second and all following slides
    \item<+(1)-> This is on the third and all following slides
    \item<+-> This is also on the third and all following slides
  \end{itemize}
\end{frame}

Notice that in this adjustment only applies to the substitution, so both the second and third lines above end up as <3-> after the automatic replacement. If you try the demo, you’ll also notice that none of the items appear on the first slide!

Perhaps a more realistic example for where an offset is useful is the case of revealing items ‘out of order’, where the full list makes sense in some other way. With hard-coded numbers this might read

\begin{frame}
  \begin{itemize}
    \item<1-> This is on the first and all following slides
    \item<2-> This is on the second and all following slides
    \item<1-> This is on the first and all following slides
    \item<2-> This is on the second and all following slides
    ...
  \end{itemize}
\end{frame}

which can be made ‘flexible’ with a set up such as

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    \item<.(-1)-> This is on the first and all following slides
    \item<.-> This is on the second and all following slides
    ...
  \end{itemize}
\end{frame}

or the equivalent

\begin{frame}
  \begin{itemize}
    \item<+-> This is on the first and all following slides
    \item<.(1)-> This is on the second and all following slides
    \item<.-> This is on the first and all following slides
    \item<+-> This is on the second and all following slides
    ...
  \end{itemize}
\end{frame}

As shown, we can use both positive and negative offsets, and these work equally well for + and . auto-generated values. You have to be slightly careful with negative offsets, as while beamer will add additional slides for positive offsets, if you offset below a final value of 0 then errors will crop up. With this rather advanced set up, which version is easiest for you to follow will be down to personal preference.

Notice that positive offsets do not include a + sign: remember what I said earlier about all + symbols being replaced. If you try something like <+(+1)>, your presentation will compile but you’ll have a lot of slides!

Summary

The beamer overlay specific can help you set up complex and flexible overlays to generate slides with dynamic content. By using the tools carefully, you can make your input easier to read and maintain.

Beamer and \subsubsection

I’m hoping to address a few bugs in beamer over the next few days. One category that is always tricky is things linked to using \subsubsection. If you’ve read the beamer manual carefully, you’ll know that the original author of the class really didn’t want people to use \subsubsection in talks. However, he also didn’t ban it entirely, leaving me with a tricky situation. The problem is that while \subsubsection works, many of the things you might expect to happen from the relationship between \section and \subsection fail with \subsubsection, and from the code that may well be ‘by design’. Of course, I can change the ‘rules’, but beamer has been around a long time and it’s also somewhat complex code. As such, I’m always having to make judgements on how to deal with these bugs. My advice: don’t use \subsubection in beamer documents! Certainly don’t be surprised if when you ignore that advice odd things happen.

Sorting beamer bugs

The beamer class is rightly regarded as the leading way to produce presentations with LaTeX. A while ago now, there was a need to find a new maintainer, and Vedran Miletić volunteered to take over. At the same time, I’d said I would be willing to at least take on some formal connection, if only to get available patches integrated into the code.

Vedran has fixed a number of bugs in beamer, but the list has been building up. I’ve spoken with Vedran about this, and as I suspected he’s rather busy! There’s also the fact that beamer works for most people most of the time. So for the moment I’m going to be dealing with keeping on top of the bug list.

As a first stage, I’m going through the list, removing anything that is not really a beamer issue (such as passing issues with hyperref) or which I can’t reproduce. I’m also picking up on bugs where there is a patch available: those can go into the code pretty much straight away. The next phase will be to sort bugs that seem to have some obvious fix. This is not so easy as beamer is rather complex internally, and I want to avoid breaking anything.

I’d expect to update CTAN once I’ve had a look through all of the bugs. Probably by the end of this week this first phase should be done, so I’d expect there to be a run of new beamer versions over the coming weeks.

I can’t promise to sort out all of the bugs, but I’d like to at least try to get the list down. If anyone wants to help out (or indeed to take over!) then they are, as usual, welcome to make contact.