\iffalse meta-comment

File: ltx-talk.tex Copyright (C) 2023-2025 Joseph Wright

It may be distributed and/or modified under the conditions of the
LaTeX Project Public License (LPPL), either version 1.3c of this
license or (at your option) any later version.  The latest version
of this license is in the file

   https://www.latex-project.org/lppl.txt

This file is part of the "ltx-talk bundle" (The Work in LPPL)
and all files in that bundle must be distributed together.

The released version of this bundle is available from CTAN.

-----------------------------------------------------------------------

The development version of the bundle can be found at

   https://github.com/josephwright/ltx-talk

for those people who are interested.

-----------------------------------------------------------------------

\fi

\DocumentMetadata{pdfversion = 2.0, lang = en}

\documentclass{l3doc}

\usepackage{siunitx}
\usepackage{unicode-math}

% Commands needed in this document
\ExplSyntaxOn
\makeatletter
\NewDocumentCommand \acro { m }
  {
    \textsc
      {
        \exp_args:NV \tl_if_head_eq_charcode:nNTF \f@series { m }
          { \text_lowercase:n }
          { \use:n }
            {#1}
      }
  }
\makeatother
\ExplSyntaxOff
\NewDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
\NewDocumentCommand\foreign{m}{\textit{#1}}
\NewDocumentCommand\opt{m}{\texttt{#1}}
\ExplSyntaxOn
\NewDocumentCommand \sarg { m } { \texttt < \__codedoc_meta:n {#1} \texttt > }
\ExplSyntaxOff
% Tidy up the above in bookmarks
\makeatletter
\pdfstringdefDisableCommands{%
  \let\acro\@firstofone
  \let\foreign\@firstofone
  \let\opt\@firstofone
}
\makeatother

% As we are dealing with a class, this has to be done manually
\def\filedate{2025-07-14}
\def\fileversion{v0.1.1}

\begin{document}

\title{%
  \cls{ltx-talk} -- A class for typesetting presentations%
  \thanks{This file describes \fileversion,
    last revised \filedate.}%
}

\author{%
  Joseph Wright%
  \thanks{%
    E-mail: \email{joseph@texdev.net}%
  }%
}

\date{Released \filedate}

\maketitle

\tableofcontents

\begin{documentation}

\section{Introduction%
  \label{sec:intro}}

The \cls{beamer} class was first released in 2003, and rapidly became the
most popular method for producing presentations in \LaTeX{}. As detailed in
the \cls{beamer} manual
\begin{quotation}
  Till Tantau created \cls{beamer} mainly in his spare time. Many other people
  have helped by sending him emails containing suggestions for improvement or
  corrections or patches or whole new themes (by now, this amounts to over a
  thousand emails concerning \cls{beamer}). Indeed, most of the development was
  only initiated by feature requests and bug reports. Without this feedback,
  \cls{beamer} would still be what it was originally intended to be: a small
  private collection of macros that make using the \cls{seminar} class easier.
  Till created the first version of \cls{beamer} for his PhD defense
  presentation in February 2003. A month later, he put the package on
  \acro{ctan} at the request of some colleagues. After that, things somehow got
  out of hand.
\end{quotation}

Despite the very large amount of work Till (and others) put into \cls{beamer},
there are several challenges which confront us today.
\begin{enumerate}
  \item The document interface is flexible but in places deviates from normal
    \LaTeX{} conventions
  \item Internally, the code makes use of whatever methods would give the
    visual results but not necessarily the most idiomatic style
  \item Till made few comments in the code or in commit messages in the code
    history
  \item The underlying box structure of a \cls{beamer} document is very
    different from the standard \LaTeX{} model, and a lot of material is
    boxed up multiple times
  \item Engine, font and macro development over the past 20 years offers
    new approaches for some areas
\end{enumerate}
These all feed into an issue addressing a major requirement today:
accessibility. Broadly, the internal structure (and to some extent the user
interface) of \cls{beamer} means that it is not possible to \enquote{retrofit}
PDF tagging into the class.

Instead, the approach is to develop a new class, \cls{ltx-talk}, which takes
ideas from \cls{beamer} but with tagging and accessibility of structure as a
design aim from the beginning. In contrast to work by the \LaTeX{} Project Team
on making the core classes accessible, the expectation for \cls{ltx-talk} is
that users \emph{will} need to change their sources. Unlike other documents,
presentations tend to be \enquote{single use}: revised and adjusted each time
they are used. The need to edit sources should therefore not be an
insurmountable barrier.

At present, this code is \emph{highly} experimental: only a (small) subset of
\cls{beamer} functionality is implemented, some things are being done
differently, and almost everything is still subject to discussion.

\section{Submitting ideas}

As noted in Section~\ref{sec:intro}, the class is at present \emph{highly}
experimental. As such, missing features or restrictions should be expected
throughout. Over time, the aim is to address many of the things that
\pkg{beamer} can do (though there may be some that are not included).

At present, prioritization of requests will be focussed on the need to provide
accessible content. This means that structural issues are likely to be handled
before design aspects.

\section{Simple example documents}

Using \cls{ltx-talk} \emph{absolutely requires} the use of the
\cs{DocumentMetadata} command. As such, the most basic \cls{ltx-talk} document
is
\begin{verbatim}
  \DocumentMetadata{} % likely with "tagging = on"
  \documentclass{ltx-talk}
  \begin{document}
  \begin{frame}
    Some content here
  \end{frame}
  \end{document}
\end{verbatim}

A slightly more useful version, which generates multiple slides and shows some
(current) features, is
\begin{verbatim}
  \DocumentMetadata{}
  \documentclass{ltx-talk}
  \begin{document}
  \begin{frame}
    \frametitle{An example frame}
    \begin{itemize}[action-spec = <+->]
      \item This will be on slide one onward
      \item This will be on slide two onward
      \item<.-> So will this
      \item But this will only appear on slide three
    \end{itemize}
    Back to appearing on all slides
  \end{frame}
  \end{document}
\end{verbatim}

Tagging is activated for the standard (projector) output of \cls{ltx-talk}, but
it is perhaps more useful in handout mode, which is activated using a class
option.
\begin{verbatim}
  \DocumentMetadata{}
  \documentclass[mode = handout]{ltx-talk}
  \begin{document}
  \begin{frame}
    \frametitle{An example frame}
    \begin{itemize}[action-spec = <+->]
      \item This will be on slide one onward
      \item This will be on slide two onward
      \item<.-> So will this
      \item But this will only appear on slide three
    \end{itemize}
    Back to appearing on all slides
  \end{frame}
  \end{document}
\end{verbatim}

A larger set of examples which can be edited and typeset in the browser are
available at \url{https://www.texdev.net/ltx-talk/examples/}.

\section{Class structure and design decisions}

As covered in Section~\ref{sec:intro}, the \cls{ltx-talk} class is currently
highly experimental. Active discussion is ongoing around many aspects of the
way that things should work, and very little is therefore at all stable. That
said, some decisions have been made: some of this is re-stating ideas which
carry forward from \cls{beamer}.
\begin{itemize}
  \item The basic structure of a presentation is made up of \env{frame}
    environments, which are made up of one or more slides.
  \item Variable content is indicated by an \emph{overlay specification}, given
    in optional angle brackets (|< ... >|).
  \item Slides have a \emph{fixed} height of \qty{100}{\mm}.
  \item The default font will be sans-serif using established standard
    implementations (currently \pkg{sansmathfonts} for \pdfTeX{} and New
    Computer Modern for OpenType engines).
\end{itemize}

\section{Differences from \cls{beamer}}

The following key differences between \cls{beamer} and \cls{ltx-talk} are
important to note for the user.
\begin{itemize}
  \item The default font setup in \cls{ltx-talk} is \emph{all} sans-serif, in
    particular \cs{mathrm} and \cs{textrm} will give a sans-serif font
  \item Overlay specifications can only be given as the first argument to
    commands
  \item Where a command takes a star as an option, this comes \emph{before}
    the overlay argument, e.g. |\includegraphics*<...>|: this reflects the
    fact that the star is usually described as part of the command name rather
    than as an argument
  \item There are no optional braced arguments in \cls{ltx-talk}, in particular
    frame titles are given using \cs{frametitle} and not as
    |\begin{frame}{...}|
  \item New overlay-aware commands and environments should be defined using
    \pkg{ltcmd} (\cs{NewDocumentCommand} and so on): no changes are made to the
    behavior of \cs{newcommand} or \cs{newenvironment}
  \item There are no commands containing the class name (or \texttt{beamer}):
    rather, methods from the kernel or other standard packages should be used
    (these are documented where needed)
  \item The class features are specifically focussed on presentation and avoid
    as far as possible other changes from standard \LaTeX{}; in particular,
    the various math-focussed additions which \cls{beamer} make (such as various
    theorem environments) are not included
\end{itemize}

\section{Creating frames}

\subsection{The frame environment}

\DescribeEnv{frame}
A presentation consists of a series of frames. Each frame consists of a series
of slides. You create a frame using the \env{frame} environment. All of the text
that is not tagged by overlay specifications is shown on all slides of the
frame. (Overlay specifications are explained in more detail in later sections.
For the moment, let's just say that an overlay specification is a list of
numbers or number ranges in angle brackets that is put after certain commands
as in |\uncover<1,2>{Text}|.) If a frame contains commands that have an overlay
specification, the frame will contain multiple slides; otherwise it contains
only one slide.

\begin{syntax}
  \cs{begin}\{\texttt{frame}\}\sarg{overlay spec}\oarg{options}
  \meta{environment contents}
  \cs{end}\{\texttt{frame}\}
\end{syntax}
The \meta{overlay spec} dictates which slides of a frame are to be shown. If
left out, the number is calculated automatically. The \meta{environment
contents} can be normal \LaTeX{} text, but may not contain |\verb| commands or
|verbatim| environments or any environment that changes the character codes.

\begin{verbatim}
  \begin{frame}
    \frametitle{A title}
    Some content
  \end{frame}
\end{verbatim}

\DescribeEnv{frame*}
The \env{frame*} environment works exactly the same way as the \env{frame} one,
\emph{except} that it can contain |\verb| commands or |verbatim| environments
or any environment that changes the character codes. The \env{frame*}
environment however \emph{cannot} be used inside the argument of another
command.
\begin{verbatim}
  \begin{frame*}
    \frametitle{A title}
    Some content \verb|$%#|.
  \end{frame*}
\end{verbatim}

In contrast to \cls{beamer}'s \opt{fragile} frame option, the \env{frame*}
environment does not use external files to handle verbatim material. As such,
there is very little performance impact processing frames containing category
code changes.

\subsection{Components of a frame}

\subsubsection{The frame title}

\DescribeMacro{\frametitle}
\begin{syntax}
  \cs{frametitle}\sarg{overlay spec}\oarg{options}\marg{frame title}
\end{syntax}
The frame title is shown prominently at the top of the frame and can be
specified with the command \cs{frametitle}. You should end the \meta{frame
title} with a period, if the title is a proper sentence. Otherwise, there
should not be a period.

\DescribeOption{frame-title-arg}
For compatibly with \cls{beamer}, the class can be loaded with the option
\opt{frame-title-arg}. When this is active, the \env{frame} environment
\emph{requires} an argument in all cases
\begin{verbatim}
  \begin{frame}{Frame title here}
\end{verbatim}
This interface is less flexible than using \cs{frametitle}, which is therefore
the recommended approach.

\subsection{Frame and margin size}

The size of a frame is actually the \enquote{paper size} of a presentation, and
it is variable. The standard size of a frame is \qty{100}{\mm} height with an
aspect ratio of $16:9$. It is the job of the presentation program to display
the slides at full screen size. The main advantage of using a small
\enquote{paper size} is that you can use all your normal fonts at their natural
sizes. In particular, inserting a graphic with \qty{11}{pt} labels will result
in reasonably sized text during the presentation.

\DescribeOption{aspect-ratio}
The aspect ratio of the slides can be adjusted by setting the
\opt{aspect-ratio} load-time option, which takes two integer values separated
by a colon. These values are the relative width and height of the slide: in
contrast to \pkg{beamer}, the absolute height is a fixed value of
\qty{100}{\mm}.

Aside from using these options, you should refrain from changing the
\enquote{paper size}. However, you \emph{can} change the size of the left and
right margins, which default to \qty{10}{\mm}. These should be set using the
interfaces from the \pkg{geometry} package, for example
\begin{verbatim}
  \geometry{lmargin = 15mm, rmargin = 15mm}
\end{verbatim}

\subsection{Restricting the slides of a frame}

The number of slides in a frame is automatically calculated. If the largest
number mentioned in any overlay specification inside the frame is~4, four
slides are introduced (despite the fact that a specification like |<4->| might
suggest that more than four slides would be possible).

\section{Creating overlays}

\subsection{The \cs{pause} command}

\DescribeMacro{\pause}
The \cs{pause} command offers an easy, but not very flexible way of creating
frames that are uncovered piecewise. If you say \cs{pause} somewhere in a
frame, only the text on the frame up to the \cs{pause} command is shown on the
first slide. On the second slide, everything is shown up to the second
\cs{pause}, and so forth. You can also use \cs{pause} inside environments; its
effect will last after the environment. However, taking this to extremes and
using \cs{pause} deeply within a nested environment may not have the desired
result.

A much more fine-grained control over what is shown on each slide can be
attained using overlay specifications, see the next sections. However, for many
simple cases the \cs{pause} command is sufficient.

The \cs{pause} command takes an optional argument
\begin{syntax}
  \cs{pause}\oarg{overlay spec}
\end{syntax}
This causes the text following it to be shown only from the next slide on, or,
if the optional \meta{overlay spec} is given, from the slide with the number
\meta{overlay spec}. If the optional \meta{overlay spec} is given, the counter
|pauses| is set to this number. This command uses the \cs{onslide} command
internally. The effect of \cs{pause} lasts till the next \cs{pause},
\cs{onslide}, or the end of the frame.
\begin{verbatim}
  \begin{frame}
    \begin{itemize}
    \item
      Shown from first slide on.
    \pause
    \item
      Shown from second slide on.
      \begin{itemize}
      \item
        Shown from second slide on.
      \pause
      \item
        Shown from third slide on.
      \end{itemize}
    \item
      Shown from third slide on.
    \pause
    \item
      Shown from fourth slide on.
    \end{itemize}

    Shown from fourth slide on.

    \begin{itemize}
    \onslide
    \item
      Shown from first slide on.
    \pause
    \item
      Shown from fifth slide on.
    \end{itemize}
  \end{frame}
\end{verbatim}

This command does \emph{not} work correctly inside math mode environments like
\env{align} and \pkg{pgf} environments like \env{tikzpicture} or
\env{tcolorbox}, since these do really wicked things.

To \enquote{unpause} some text, that is, to temporarily suspend pausing, use
the command \cs{onslide}, see below.

\subsection{The general concept of overlay specifications}

Whilst the \cs{pause} command is easy to understand, it is quite limited and so
is best suited only to simple cases. The \cls{ltx-talk} class therefore
supports a different approach. The idea is to add \emph{overlay specifications}
to commands. These specifications are always given in pointed brackets and
follow the command as the first argument. In the simplest case, the
specification contains just a number. A command with an overlay specification
following it will only have \enquote{effect} on the slide(s) mentioned in the
specification. What exactly \enquote{having an effect} means, depends on the
command. Consider the following example.
\begin{verbatim}
  \begin{frame}
    \textbf{This line is bold on all three slides.}
    \textbf<2>{This line is bold only on the second slide.}
    \textbf<3>{This line is bold only on the third slide.}
  \end{frame}
\end{verbatim}

For the command \cs{textbf}, the overlay specification causes the text to be
set in boldface only on the specified slides. On all other slides, the text is
set in a normal font.

For a second example, consider the following frame:
\begin{verbatim}
  \begin{frame}
    \only<1>{This line is inserted only on slide~1.}
    \only<2>{This line is inserted only on slide~2.}
  \end{frame}
\end{verbatim}

The command \cs{only} normally simply inserts its parameter into the current
frame. However, if an overlay specification is present, it \enquote{throws
away} its parameter on slides that are not mentioned.

Overlay specifications can only be written behind certain commands, not every
command. Which commands you can use and which effects this will have is
explained in the next section. However, it is quite easy to redefine an
existing command such that it becomes \enquote{overlay specification aware},
see also Section~\ref{sec:overlay-cmds}.

The syntax of (basic) overlay specifications is the following: they are
comma-separated lists of slides and ranges. Ranges are specified like this:
|2-5|, which means slide two through to five. The start or the end of a range
can be omitted. For example, |3-| means \enquote{slides three, four, five, and
so on} and |-5| means the same as |1-5|. A complicated example is
|-3,6-8,10,12-15|, which selects the slides 1, 2, 3, 6, 7, 8, 10, 12, 13, 14
and~15.

\subsection{Commands with overlay specifications%
  \label{sec:overlay-cmds}}

For the following commands, adding an overlay specification causes the command
to be simply ignored on slides that are not included in the specification:
\cs{textbf}, \cs{textit}, \cs{textmd}, \cs{textnormal}, \cs{textrm},
\cs{textsc}, \cs{textsf}, \cs{textsl}, \cs{texttt}, \cs{textup}, \cs{emph};
\cs{color}, \cs{mathcolor}, \cs{textcolor}; \cs{alert}, \cs{structure};
\cs{includegraphics}; \cs{label}.

If a command takes several arguments, like \cs{color}, the specification should
directly follow the command as in the following example:
\begin{verbatim}
  \begin{frame}
    \color<2-3>[rgb]{1,0,0} This text is red on slides 2 and 3, otherwise
      black.
  \end{frame}
\end{verbatim}

For the following commands, the effect of an overlay specification is special:

\DescribeMacro{\onslide}
\begin{syntax}
  \cs{onslide}\sarg{overlay spec}
\end{syntax}
All text following this command will only be shown (uncovered) on the specified
slides. On non-specified slides, the text still occupies space. If no slides
are specified, the following text is always shown. You need not call this
command in the same \TeX{} group, its effect transcends block groups.
\begin{verbatim}
  \begin{frame}
    Shown on first slide.
    \onslide<2-3>
    Shown on second and third slide.
    \begin{itemize}
    \item
      Still shown on the second and third slide.
    \onslide<4->
    \item
      Shown from slide~4 on.
    \end{itemize}
    Shown from slide~4 on.
    \onslide
    Shown on all slides.
  \end{frame}
\end{verbatim}

\DescribeMacro{\only}
\begin{syntax}
  \cs{only}\sarg{overlay spec}\marg{text}
\end{syntax}
The \meta{text} is inserted only into the specified slides. For other slides, 
the text is simply thrown away. In particular, it occupies no space.
\begin{verbatim}
  \only<3->{Text inserted from slide 3 on.}
\end{verbatim}

\DescribeMacro{\uncover}
\begin{syntax}
  \cs{uncover}\sarg{overlay spec}\marg{text}
\end{syntax}
If the \meta{overlay spec} is present, the \meta{text} is shown
(\enquote{uncovered}) only on the specified slides. On other slides, the text
still occupies space and it is still typeset, but it is not shown or only shown
as if transparent. For details on how to specify whether the text is invisible
or just transparent see Section~\ref{sec:opacity}.
\begin{verbatim}
  \uncover<3->{Text shown from slide 3 on.}
\end{verbatim}

\DescribeMacro{\visible}
\begin{syntax}
  \cs{visible}\sarg{overlay spec}\marg{text}
\end{syntax}
This command does almost the same as \cs{uncover}. The only difference is that
if the text is not shown, it is never shown in a transparent way, but rather it
is not shown at all. Thus, for this command the transparency settings have no
effect.
\begin{verbatim}
  \visible<2->{Text shown from slide 2 on.}
\end{verbatim}

\DescribeMacro{\invisible}
\begin{syntax}
  \cs{invisible}\sarg{overlay spec}\marg{text}
\end{syntax}
This command does the opposite of \cs{visible}.
\begin{verbatim}
  \invisible<2->{Text hidden from slide~2 on.}
\end{verbatim}

\DescribeMacro{\alt}
\begin{syntax}
  \cs{alt}\sarg{overlay spec}\marg{default text}\marg{alternative text}
\end{syntax}
The default text is shown on the specified slides, otherwise the alternative
text.
\begin{verbatim}
  \alt<2>{On slide~2}{Not on slide~2.}
\end{verbatim}

\DescribeMacro{\temporal}
\begin{syntax}
  \cs{temporal}\sarg{overlay spec}\marg{before slide text}\marg{default text}%
    \marg{after slide text}
\end{syntax}
This command alternates between three different texts, depending on whether the
current slide is temporally before the specified slides, is one of the
specified slides, or comes after them. If the \meta{overlay spec} is not an
interval (that is, if it has a \enquote{hole}), the \enquote{hole} is
considered to be part of the before slides.
\begin{verbatim}
  \temporal<3-4>{Shown on 1, 2}{Shown on 3, 4}{Shown 5, 6, 7, ...}
  \temporal<3,5>{Shown on 1, 2, 4}{Shown on 3, 5}{Shown 6, 7, 8, ...}
\end{verbatim}
As a possible application of the \cs{temporal} command consider the following
example:
\begin{verbatim}
  \NewDocumentCommand\colorize{D<>{all}{%
    \temporal<#1>{\color{red!50}}{\color{black}}{\color{black!50}}}
  \begin{frame}
    \begin{itemize}
      \colorize<1> \item First item.
      \colorize<2> \item Second item.
      \colorize<3> \item Third item.
      \colorize<4> \item Fourth item.
    \end{itemize}
  \end{frame}
\end{verbatim}

\DescribeMacro{\item}
\begin{syntax}
  \cs{item}\sarg{action spec}\oarg{item label}
\end{syntax}
The effect of \meta{action spec} is described in Section~\ref{sec:action-spec};
this extends the \meta{overlay spec} to include the potential to
\enquote{alert} items.
\begin{verbatim}
  \begin{frame}
    \begin{itemize}
    \item<1-> First point, shown on all slides.
    \item<2-> Second point, shown on slide~2 and later.
    \item<2-> Third point, also shown on slide~2 and later.
    \item<3-> Fourth point, shown on slide~3.
    \end{itemize}
  \end{frame}

  \begin{frame}
    \begin{enumerate}
    \item<3-| alert@3>[0.] A zeroth point, shown at the very end.
    \item<1-| alert@1> The first and main point.
    \item<2-| alert@2> The second point.
    \end{enumerate}
  \end{frame}
\end{verbatim}

\subsection{Environments with overlay specifications}

\DescribeEnv{onlyenv}
\DescribeEnv{invisibleenv}
\DescribeEnv{uncoverenv}
\DescribeEnv{visibleenv}
For each of the basic commands \cs{only}, \cs{visible}, \cs{uncover} and
\cs{invisible} there exists \enquote{environment versions} \env{onlyenv},
\env{visibleenv}, \env{uncoverenv} and \env{invisibleenv}. Except for
\env{onlyenv}, these environments do the same as the commands.

For the \env{onlyenv} environment, the contents of the environment is inserted
into the text only on the specified slides. The difference to \cs{only} is,
that the text is actually typeset inside a box that is then thrown away,
whereas \cs{only} immediately throws away its contents. If the text is not
\enquote{typesettable}, the \env{onlyenv} may produce an error where \cs{only}
would not.
\begin{verbatim}
  \begin{frame}
    This line is always shown.
    \begin{onlyenv}<2>
      This line is inserted on slide~2.
    \end{onlyenv}
  \end{frame}
\end{verbatim}

\subsection{Dynamically changing text or images}

You may sometimes wish to have some part of a frame change dynamically from
slide to slide. On each slide of the frame, something different should be shown
inside this area. You could achieve the effect of dynamically changing text by
giving a list of \cs{only} commands like this:
\begin{verbatim}
  \only<1>{Initial text.}
  \only<2>{Replaced by this on second slide.}
  \only<3>{Replaced again by this on third slide.}
\end{verbatim}

The trouble with this approach is that it may lead to slight, but annoying
differences in the heights of the lines, which may cause the whole frame to
\enquote{wobble} from slide to slide. This problem becomes much more severe if
the replacement text is several lines long.

To solve this problem, you can use two environments: \env{overlayarea} and
\env{overprint}. The first is more flexible, but less user-friendly.

\DescribeEnv{overlayarea}
\begin{syntax}
  \cs{begin}\{overlayarea\}\marg{area width}\marg{area height}
\end{syntax}
Everything within the environment will be placed in a rectangular area of the
specified size. The area will have the same size on all slides of a frame,
regardless of its actual contents.
\begin{verbatim}
  \begin{overlayarea}{\textwidth}{3cm}
    \only<1>{Some text for the first slide.\\Possibly several lines long.}
    \only<2>{Replacement on the second slide.}
  \end{overlayarea}
\end{verbatim}

\DescribeEnv{overprint}
\begin{syntax}
  \cs{begin}\{overprint\}\oarg{area width}
\end{syntax}
The \meta{area width} defaults to the text width. Inside the environment, use
\cs{only} or \env{onlyenv} to specify different things that should be shown for
this environment on different slides. Everything within the environment will be
placed in a rectangular area of the specified width. The height and depth of
the area are chosen large enough to accommodate the largest contents of the
area. Two compilations will be needed to allow \LaTeX{} to track the tallest
version of the frame contents.
\begin{verbatim}
  \begin{overprint}
    \only<1|handout:1>{%
        Some text for the first slide.\\
        Possibly several lines long.
      }%
    \only<2|handout:0>{%
       Replacement on the second slide. Suppressed for handout.
     }%
  \end{overprint}
  Following text
\end{verbatim}

A similar need for dynamical changes arises when you have, say, a series of
pictures named \file{first}, \file{second}, and \file{third} that show
different stages of some process. To make a frame that shows these pictures on
different slides, the following code might be used:
\begin{verbatim}
  \begin{frame}
    \frametitle{The Three Process Stages}

    \includegraphics<1>{first}
    \includegraphics<2>{second}
    \includegraphics<3>{third}
  \end{frame}
\end{verbatim}

\subsection{Advanced overlay specifications}

\subsubsection{Mode specifications}

This section is only important if you use the mode mechanism to create
different versions of your presentation. If you are not familiar with modes,
please skip this section or read Section~\ref{sec:modes} first.

In certain cases you may wish to have different overlay specifications to apply
to a command in different modes. For example, you might wish a certain text to
appear only from the third slide on during your presentation, but in a handout
for the audience there should be no third slide and the text should appear
already on the second slide. In this case you could write
\begin{verbatim}
  \only<3| handout:2>{Some text}
\end{verbatim}

The vertical bar separates the two different specifications |3| and
|handout:2|. By writing a mode name before a colon, you specify that the
following specification only applies to that mode. If no mode is given, as in
|3|, the mode |projector| is automatically added. For this reason, if you write
|\only<3>{Text}| and you are in |handout| mode, the text will be shown on all
slides since there is no restriction specified for handouts and since the |3|
is the same as |projector:3|.

It is also possible to give an overlay specification that contains only a mode
name (or several, separated by vertical bars):
\begin{verbatim}
  \only<handout>{This text is shown only in handout mode.}
\end{verbatim}

An overlay specification that does not contain any slide numbers is called a
(pure) \emph{mode specification}. If a mode specification is given, all modes
that are not mentioned are automatically suppressed. Thus |<projector:1->|
means \enquote{on all slides in |projector| mode and also on all slides in all
other modes, since nothing special is specified for them}, whereas
|<projector>| means \enquote{on all slides in |projector| mode and not on any
other slide}.

You can also mix pure mode specifications and overlay specifications, although
this can get confusing:
\begin{verbatim}
  \only<article| projector:1>{Riddle}
\end{verbatim}

This will cause the text |Riddle| to be inserted in |article| mode and on the
first slide of a frame in |projector| mode, but not at all in |handout| mode.

\subsubsection{Action specifications%
  \label{sec:action-spec}}

This section also introduces a rather advanced concept. You may also wish to
skip it on first reading.

Some overlay specification-aware commands can handle not only normal overlay
specifications, but also a so called \emph{action spec}. In an action
specification, the list of slide numbers and ranges is prefixed by
\meta{action}|@|, where \meta{action} is the name of a certain action to be
taken on the specified slides:
\begin{verbatim}
  \item<3-|alert@3> Shown from slide~3 on, alerted on slide~3.
\end{verbatim}

In the above example, the \cs{item} command, which allows actions to be
specified, will uncover the item text from slide three on and it will,
additionally, alert this item exactly on slide~3.

Not all commands can take an action specification. Currently, only \cs{item},
\cs{action}, the environment \env{actionenv}, and the block environments (like
\env{block}) handle them.

By default, the following actions are available:
\begin{itemize}
  \item |alert| alters the item or block.
  \item |uncover| uncovers the item or block (this is the default, if no action
    is specified).
  \item |only| causes the whole item or block to be inserted only on the
    specified slides.
  \item |visible| causes the text to become visible only on the specified
    slides (the difference between |uncover| and |visible| is the same as
    between \cs{uncover} and \cs{visible}).
  \item |invisible| causes the text to become invisible on the specified
    slides.
\end{itemize}

The whole action mechanism is based on the following environment:
\DescribeEnv{actionenv}
\begin{syntax}
  \cs{begin}\{actionenv\}\sarg{action spec}
\end{syntax}
This environment extracts all actions from the \meta{action spec} for the
current mode. For each action of the form \meta{action}|@|\meta{slide numbers},
it inserts the equivalent internal code to:
|\begin{|\meta{action}|env}<|\meta{slide number}|>| at the beginning of the
environment and the text |\end{|\meta{action}|env}| at the end. An
\meta{overlay spec} without an action is promoted to |uncover@|\meta{overlay
spec}.
\begin{verbatim}
  \begin{frame}
    \begin{actionenv}<2-|alert@3-4,6>
      This text is shown the same way as the text below.
    \end{actionenv}

    \begin{uncoverenv}<2->
      \begin{alertenv}<3-4,6>
        This text is shown the same way as the text above.
      \end{alertenv}
    \end{uncoverenv}
  \end{frame}
\end{verbatim}

\DescribeMacro{\action}
\begin{syntax}
  \cs{action}\sarg{action spec}\marg{text}
\end{syntax}
This has the same effect as putting \meta{text} in an \env{actionenv}.

\subsubsection{Incremental specifications%
  \label{sec:incremental}}

This section is mostly important for people who have already used overlay
specifications a lot and have grown tired of writing things like |<1->|,
|<2->|, |<3->|, and so on again and again. You should skip this section on
first reading.

Often you want to have overlay specifications that follow a pattern similar to
the following:
\begin{verbatim}
  \begin{itemize}
    \item<1-> Apple
    \item<2-> Peach
    \item<3-> Plum
    \item<4-> Orange
  \end{itemize}
\end{verbatim}

The problem starts if you decide to insert a new fruit, say, at the beginning.
In this case, you would have to adjust all of the overlay specifications. Also,
if you add a \cs{pause} command before the |itemize|, you would also have to
update the overlay specifications.

The class offers a special syntax to make creating lists as the one above more
convenient. You can replace it by the following list of \emph{incremental
overlay specifications}:
\begin{verbatim}
  \begin{itemize}
    \item<+-> Apple
    \item<+-> Peach
    \item<+-> Plum
    \item<+-> Orange
  \end{itemize}
\end{verbatim}

The effect of the |+| sign is the following: You can use it in any overlay
specification at any point where you would usually use a number. If a |+| sign
is encountered, it is replaced by the current value of the \LaTeX{} counter
|pauses|, which is~$1$ at the beginning of the frame. Then the counter is
increased by~$1$, though it is only increased once for every overlay
specification, even if the specification contains multiple |+| signs (they are
replaced by the same number).

In the above example, the first specification is replaced by |<1->|. Then the
second is replaced by |<2->| and so forth. We can now easily insert new
entries, without having to change anything else. We might also write the
following:
\begin{verbatim}
  \begin{itemize}
    \item<+-| alert@+> Apple
    \item<+-| alert@+> Peach
    \item<+-| alert@+> Plum
    \item<+-| alert@+> Orange
  \end{itemize}
\end{verbatim}

This will alert the current item when it is uncovered. For example, the first
specification \verb"<+-| alert@+>" is replaced by \verb"<1-| alert@1>", the
second is replaced by \verb"<2-| alert@2>", and so on. Since the \env{itemize}
environment also allows you to specify a default overlay specification, see the
documentation of that environment, the above example can be written even more
economically as follows:
\begin{verbatim}
  \begin{itemize}[<+-| alert@+>]
    \item Apple
    \item Peach
    \item Plum
    \item Orange
  \end{itemize}
\end{verbatim}

The \cs{pause} command also updates the counter |pauses|. You can change this
counter yourself using the normal \LaTeX{} commands \cs{setcounter} or
\cs{addtocounter}.

Any occurrence of a |+| sign may be followed by an \emph{offset} in round
brackets. This offset will be added to the value of the |pauses| counter. Thus,
if |pauses| is $2$, then |<+(1)->| expands to |<3->| and |<+(-1)-+>| expands to
|<1-2>|. For example
\begin{verbatim}
  \begin{itemize}
    \item<2-> Apple
    \item<3-> Peach
    \item<4-> Plum
    \item<5-> Orange
  \end{itemize}
\end{verbatim}
and
\begin{verbatim}
  \begin{itemize}[<+(1)->]
    \item Apple
    \item Peach
    \item Plum
    \item Orange
  \end{itemize}
\end{verbatim}
are equivalent.

There is another special sign you can use in an overlay specification that
behaves similarly to the |+| sign: a dot. When you write |<.->|, a similar
thing as in |<+->| happens \emph{except} that the counter |pauses| is
\emph{not} incremented and \emph{except} that you get the value of |pauses|
decreased by one. Thus a dot, possibly followed by an offset, just expands to
the current value of the counter |pauses| minus one, possibly offset. This dot
notation can be useful in case like the following:
\begin{verbatim}
  \begin{itemize}[<+->]
    \item Apple
    \item<.-> Peach
    \item Plum
    \item Orange
  \end{itemize}
\end{verbatim}

In the example, the second item is shown at the same time as the first one
since it does not update the counter.

In the following example, each time an item is uncovered, the specified text is
alerted. When the next item is uncovered, this altering ends.
\begin{verbatim}
  \begin{itemize}[<+->]
    \item This is \alert<.>{important}.
    \item We want to \alert<.>{highlight} this and \alert<.>{this}.
    \item What is the \alert<.>{matrix}?
  \end{itemize}
\end{verbatim}

The replacements of the |+| sign and the |.| sign are no less than zero. This
prevents errors when encountering large negative offsets, for example
|<+(-7)->| is converted to |<0->| rather than |<-6->|.

\section{Structuring a presentation: the local structure}

\LaTeX{} provides different commands for structuring text \enquote{locally},
for example, \foreign{via} the \env{itemize} environment. These environments
are also available in the \cls{ltx-talk} class, although their appearance has
been slightly changed.

\subsection{Itemizations, enumerations and descriptions}

\DescribeEnv{description}
\DescribeEnv{enumerate}
\DescribeEnv{itemize}
There are three predefined environments for creating lists, namely
\env{enumerate}, \env{itemize}, and \env{description}. The first two can be
nested to depth three, but nesting them to this depth creates totally
unreadable slides.

\DescribeMacro{\item}
The \cs{item} command is overlay specification-aware. If an overlay
specification is provided, the item will only be shown on the specified slides,
see the following example. If the \cs{item} command is to take an optional
argument and an overlay specification, the overlay specification comes first as
in |\item<1>[Cat]|.
\begin{verbatim}
  \begin{frame}
    There are three important points:
    \begin{enumerate}
      \item<1-> A first one,
      \item<2-> a second one with a bunch of subpoints,
        \begin{itemize}
          \item first subpoint. (Only shown from second slide on!).
          \item<3-> second subpoint added on third slide.
          \item<4-> third subpoint added on fourth slide.
        \end{itemize}
      \item<5-> and a third one.
    \end{enumerate}
  \end{frame}
\end{verbatim}

The list environments have syntax
\begin{syntax}
  \cs{begin}\marg{list type}\oarg{options}
\end{syntax}

If the option \opt{action-spec} is given, in every occurrence of an \cs{item}
command that does not have an overlay specification attached to it, the
\meta{overlay specification} is used. By setting this specification to be an
incremental overlay specification, see Section~\ref{sec:incremental}, you
can implement, for example, a stepwise uncovering of the items. The
\meta{overlay specification} is inherited by subenvironments.
Naturally, in a subenvironment you can reset it locally by setting it to
|<1->| (the subitems will be shown on all slides) or |<.->| (the subitems will
be shown starting from the same slide as the parent item).
\begin{verbatim}
  \begin{itemize}[action-spec = <+->]
    \item This is shown from the first slide on.
    \item This is shown from the second slide on.
    \item This is shown from the third slide on.
    \item<1-> This is shown from the first slide on.
    \item This is shown from the fourth slide on.
  \end{itemize}
\end{verbatim}
If you do not need to give any other options for the list environment, you may
use the shortened format |[<...>]|, which matches the \cls{beamer} syntax:
\begin{verbatim}
  \begin{itemize}[<+->]
    \item This is shown from the first slide on.
    \item This is shown from the second slide on.
    \item This is shown from the third slide on.
    \item<1-> This is shown from the first slide on.
    \item This is shown from the fourth slide on.
  \end{itemize}
\end{verbatim}

\subsection{Highlighting}

\DescribeMacro{\alert}
\begin{syntax}
  \cs{alert}\sarg{overlay spec}\marg{text}
\end{syntax}
The given \meta{text} is highlighted, typically by coloring the text red. If
the \meta{overlay spec} is present, the command only has an effect on the
specified slides.
\begin{verbatim}
  This is \alert{important}.
\end{verbatim}

\DescribeEnv{alertenv}
\begin{syntax}
  \cs{begin}\{\texttt{alertenv}\}\sarg{overlay spec}
\end{syntax}
Environment version of the \cs{alert} command.

\subsection{Block environments}

\subsection{Splitting a frame into multiple columns}

The class offers several commands and environments for splitting (perhaps only
part of) a frame into multiple columns. These commands have nothing to do with
\LaTeX{}'s commands for creating columns. Columns are especially useful for
placing a graphic next to a description/explanation.

The main environment for creating columns is called \env{columns}. Inside this
environment, you can place several \env{column} environments, each of which
creates a new column.

\DescribeEnv{columns}
\begin{syntax}
  \cs{begin}\{\texttt{columns}\}\sarg{action spec}\oarg{options}
\end{syntax}
A multi-column area. If the \meta{action spec} is present, the given actions
are taken on the specified slides, see Section~\ref{sec:action-spec}. The
following \meta{options} may be given:
\begin{itemize}
  \item \opt{vertical-alignment} a choice of one of \opt{bottom}, \opt{center}
    or \opt{top}; this causes the content of the columns to be aligned as
    specified. The standard setting is \opt{center}. For compatibility with
    \cls{beamer}, the short options \opt{b}, \opt{c} and \opt{t} are available.
  \item \opt{width} will cause the columns to occupy \meta{width}: the standard
    setting is \cs{textwidth}.
\end{itemize}

\DescribeEnv{column}
\begin{syntax}
  \cs{begin}\{\texttt{column}\}\sarg{action spec}\oarg{placement}\marg{column width}
\end{syntax}
To create a column, you can use the \env{column} environment.
\begin{verbatim}
  \begin{columns}
    \begin{column}{5cm}
      Two\\lines.
    \end{column}
    \begin{column}{5cm}
      One line (but aligned).
    \end{column}
  \end{columns}
\end{verbatim}

Creates a single column of width \meta{column width}. If the \meta{action
specification} is present, the given actions are taken on the specified slides,
see Section~\ref{sec:action-spec}. The vertical placement of the enclosing
\env{columns} environment can be overruled by specifying a specific
\meta{placement}.

\section{Creating alternative output formats%
  \label{sec:modes}}

\DescribeOption{mode}
The \cls{ltx-talk} class allows you to select different output formats from the
same source using the option \opt{mode}. This works with the overlay
specification to typeset some of the input selectively.

\subsection{Creating handouts using the \opt{handout} mode}
  
During a presentation it is very much desirable that the audience has a
\emph{handout} or even \emph{lecture notes} available to it. A handout allows
everyone in the audience to individually go back to things they have not
understood.

The easiest way of creating a handout for your audience is to set the
\opt{mode} option set to \meta{handout}. This will cause the document to be
typeset in |handout| mode. It will look like a presentation, but it can be
printed or annotated more easily (the overlays are \enquote{flattened}).

\section{Creating tagging PDF output}

As detailed in the introduction (Section~\ref{sec:intro}), the \cls{ltx-talk}
class has been written from the start with tagging in mind. As such, where
possible, tagging is generated automatically. This works best with predictable
frame structure, for example the classical \enquote{uncover a list one item at
a time} approach.

\DescribeOption{tag-slides}
To enable control tagging of slides, the frame option \opt{tag-slides} is
available. This can be used to list which slides in a frame are tagged: those
omitted are marked as artifacts. The setting should be a comma-list of slide
numbers, which an include \opt{n} as a marker to mean the last slide of the
frame. The standard setting is \opt{tag-slides = n}, meaning only the last
slide of the frame is tagged. You may use mode specifications in the
\opt{tag-slides} option, for example \opt{tag-slides = n\|handout:1,n} would
tag the last slide in the frame in \texttt{projector} mode and the first and
last for \texttt{handout} mode.

\end{documentation}

\PrintIndex

\end{document}