While preparing my slides for the upcoming Dutch LaTeX course I'll be giving (if you're interested, contact me) for our ACM Student Chapter I got puzzled by the fact beamer requires me to use [fragile] as the option to every slide containing verbatim text. I decided to figure it out.

First, what does fragile mean? It has to do with expansion and execution: TeX does these at the same time, first it reads an token, expands it so that only low-level tokens are left and then executes it. But this cycle isn't always followed: for instance when moving text around this behaviour changes.

When will TeX move text? For instance when creating a table of contents: the \section{}'s are scattered throughout your document, but in the end they all end up in your table of contents. When expanding and executing a \section{} command it will write the current section's title and number to a .toc file. A second pass then fills in the table of contents, based on the data that was written in the first pass.

A command that is not fragile is called robust by the way.

So, why is this a problem? The meaning of code changes during TeX's process and only when the typesetting is done, the actual meaning can be determined. So when writing to data to a file, some expansions must not occur, because they are dependent on the current situation (in the table of contents case: when we're typesetting the table of contents, as opposed to typesetting the actual \section{}'s). Examples of these are:

  • commands with optional arguments
  • line breaks
  • footnotes
  • inline math

How should I deal with these issues? Just prefix it with \protect, your fragile command is now protected. But this is not the point of this post. I was interested in why beamer so desperately needs the [fragile] option when typesetting slides containing verbatim text.

Section 12.9 of the manual states the following on the issue:

If you wish to use a {verbatim} environment in a frame, you have to add the option [fragile] to the {frame} environment. In this case, [...] and the \end{frame} must be alone on a single line. Using this option will cause the frame contents to be written to an external file and the read back.

Not really a satisfactory answer, it only states what we already knew about fragile commands and their usage. And it signifies some of the weird things going on with beamer: somehow the whitespace in front of \end{frame} got a special meaning. Rather scary, don't you think?

But we're not interested in TeX voodoo, we want an explanation for [fragile]. A closer inspection of Section 8.1 which defines {frame} reveals the following:

If a frame contains fragile text, different internal mechanisms are used to typeset the frame to ensure that inside the frame the character codes can be reset. The price of switching to another internal mechanism is that either you cannot use overlays or an external file needs to be written and read back (which is not always desirable).

In detail, the following happens when this option is given for normal (pdf)LaTeX: The contents of the frame is scanned and then written to a special file named ⟨jobname⟩.vrb or, if a label has been assigned to the frame, ⟨jobname⟩.⟨current frame number⟩.vrb. Then, the frame is started anew and the content of this file is read back. Since, upon reading of a file, the character codes can be modified, this allows you to use both verbatim text and overlays.

To determine the end of the frame, the following rule is used: The first occurence of a single line containing exactly \end{⟨frame environment name⟩} ends the frame. The ⟨environment name⟩ is normally frame, but it can be changed using the environment option. This special rule is needed since the frame contents is, after all, not interpreted when it is gathered.

Now we're getting somewhere: beamer's internal magic is really, well, quite magical. It fiddles with character codes, the stuff that makes TeX work like you expect it to. But TeX is highly adaptable, no one imposes that your syntax should be \command{parameter}, it can easily be changed to |code[parameter]. There are two cases I can come up with right now where this is a good idea: verbatim text and packages performing magic. beamer is one of the latter, but it should work together with verbatim text as well, hence the hassle.

An example of beamer's use of character codes are the greater-than and less-than symbol: they are active characters for beamer. They are for instance used when changing the mode of the presentation (something you do when you're both creating a presentation and handouts). Now verbatim text also changes the (local) meaning of these characters. And this is exactly why you need the [fragile] option.

A downside of this construction is an extended build time: all fragile frames are written to a file (you can read these files when building your document, that's how I found out in the first place) and then read again. But the singleslide option seems to eliminate this for frames without \pause's or other kinds of overlays. Hurray!