%% ---------------------------------------------------------------------------
%% Copyright 2015 Matthias Vogelgesang and the LaTeX community. A full list of
%% contributors can be found at
%%
%%     https://github.com/matze/mtheme/graphs/contributors
%%
%% and the original template was based on the HSRM theme by Benjamin Weiss.
%%
%% This work is licensed under a Creative Commons Attribution-ShareAlike 4.0
%% International License (https://creativecommons.org/licenses/by-sa/4.0/).
%% ---------------------------------------------------------------------------

\documentclass{ltxdoc}
%\OnlyDescription

\usepackage{parskip}
\usepackage{setspace}
\usepackage{xspace}
\onehalfspacing

\usepackage{etoolbox}
\usepackage{ifxetex}
\usepackage{ifluatex}

\ifboolexpr{bool {xetex} or bool {luatex}}{
  \usepackage{fontspec}
  \defaultfontfeatures{Ligatures=TeX}

  \newcounter{fontsnotfound}
  \newcommand{\checkfont}[1]{%
    \suppressfontnotfounderror=1%
    \font\x = "#1" at 10pt
    \selectfont
    \ifx\x\nullfont%
      \stepcounter{fontsnotfound}%
    \fi%
    \suppressfontnotfounderror=0%
  }

  \newcommand{\iffontsavailable}[3]{%
    \setcounter{fontsnotfound}{0}%
    \expandafter\forcsvlist\expandafter%
    \checkfont\expandafter{#1}%
    \ifnum\value{fontsnotfound}=0%
      #2%
    \else%
      #3%
    \fi%
  }
  \iffontsavailable{Fira Sans Light,%
                Fira Sans Light Italic,%
                Fira Sans,%
                Fira Sans Italic}{%
    \setmainfont[BoldFont={Fira Sans}]{Fira Sans Light}%
  }{%
    \iffontsavailable{Fira Sans Light OT,%
                  Fira Sans Light Italic OT,%
                  Fira Sans OT,%
                  Fira Sans Italic OT}{%
      \setmainfont[BoldFont={Fira Sans OT}]{Fira Sans Light OT}%
    }{%
      \typeout{%
        Could not find Fira Sans fonts. Creating documentation%
        with standard fonts.%
      }
    }
  }
  \iffontsavailable{Fira Mono, Fira Mono Bold}{%
    \setmonofont{Fira Mono}%
  }{%
    \iffontsavailable{Fira Mono OT, Fira Mono Bold OT}{%
      \setmonofont{Fira Mono OT}%
    }{%
      \typeout{%
        Could not find Fira Sans fonts. Creating documentation%
        with standard monospaced fonts.%
      }
    }
  }
}{
  \typeout{%
    You need to compile with XeLaTeX or LuaLaTeX to use the Fira fonts.%
  }
}

\usepackage{enumitem}
\setlist[itemize]{noitemsep}
\setlist[enumerate]{noitemsep}

\usepackage{xcolor}
\definecolor{mDarkBrown}{HTML}{604c38}
\definecolor{mDarkTeal}{HTML}{23373b}
\definecolor{mLightBrown}{HTML}{EB811B}
\definecolor{mLightGreen}{HTML}{14B03D}
\definecolor{mBackground}{HTML}{FFFFFF}

\usepackage{listings}
\lstset{%
  language=[LaTeX]{TeX},
  basicstyle=\ttfamily,
  keywordstyle=\color{mLightBrown}\bfseries,
  commentstyle=\color{mLightGreen},
  stringstyle=\color{mLightGreen},
  backgroundcolor=\color{mBackground},
  numbers=none,
  numberstyle=\tiny\ttfamily,
  stepnumber=2,
  showspaces=false,
  showstringspaces=false,
  showtabs=false,
  frame=none,
  framerule=1pt,
  tabsize=2,
  rulesep=5em,
  captionpos=b,
  breaklines=true,
  breakatwhitespace=false,
  framexleftmargin=0em,
  framexrightmargin=0em,
  xleftmargin=0em,
  xrightmargin=0em,
  aboveskip=1em,
  belowskip=1em,
  morekeywords={usetheme,institute,maketitle,@metropolis@titleformat,%
                plain,setbeamercolor,metroset,setsansfont,setmonofont},
}
\lstMakeShortInline|
\usepackage{metalogo}

\usepackage[colorlinks=true,
            linkcolor=mLightBrown,
            menucolor=mLightBrown,
            pagecolor=mLightBrown,
            urlcolor=mLightBrown]{hyperref}

\newcommand{\DescribeOption}[4]{
  \DescribeMacro{#1}
  \begin{minipage}[t]{\textwidth}
    \textit{\textbf{\textcolor{mLightGreen}{#2}}}\dotfill\,#3\par
    \begingroup
    \vspace{0.5em}#4\par
    \endgroup
  \end{minipage}
}

\newcommand{\themename}{\textbf{\textsc{metropolis}}\xspace}

\usepackage{readprov}
\ReadPackageInfos{beamerthememetropolis}

\title{Modern Beamer Presentations with the \themename package}
\author{Matthias Vogelgesang \\ \url{matthias.vogelgesang@gmail.com}}
\date{\fileversion~---~\filedate}

\begin{document}

\maketitle
\tableofcontents


\section{Introduction}

Beamer is an awesome way to make presentations with LaTeX, but its theme
selection is surprisingly sparse. The stock themes share an aesthetic that can
be a little cluttered, while the few distinctive custom themes available are
often specialized for a particular corporate or institutional brand.

The goal of \themename is to provide a simple, modern Beamer theme suitable
for anyone to use. It tries to minimize noise and maximize space for content;
the only visual flourish it offers is an (optional) progress bar added to each
slide or to the section slides.

By default, \themename uses
\href{https://www.mozilla.org/en-US/styleguide/products/firefox-os/typeface/}
{Fira Sans}, a gorgeous typeface commissioned by Mozilla and designed by
\href{http://www.carrois.com/fira-3-1/}{Carrois}. For best results, you will
need the Fira typeface installed and use \XeLaTeX\ to typeset your slides.
However, \themename can also be used with other typefaces and \LaTeX{} build
systems.

\themename's codebase is maintained on \href{https://github.com/matze/mtheme}
{GitHub}. If you have issues, find mistakes in the manual or want to help make
the theme even better, please get in touch there. The
\href{https://github.com/matze/mtheme/graphs/contributors}
{full list of contributors} already contains over a dozen names!


\section{Getting Started}

\subsection{Installing from CTAN}

For most users, we recommend installing \themename from
\href{https://www.ctan.org}{CTAN}. If you keep your \TeX\ distribution
up-to-date, chances are good that \themename is already installed. If it is
not, you need to update your packages. If your distribution is \TeX\ Live
(or Mac\TeX\ on OS X), the following command updates all packages.

\begin{lstlisting}
tlmgr update --all
\end{lstlisting}

If this results in an error, you may need to run it with administrative privileges:

\begin{lstlisting}
sudo tlmgr update --all
\end{lstlisting}

Mac\TeX\ on OS X also provides a graphical interface for |tlmgr| called
\TeX\ Live Utility.

For any other distribution please refer to its documentation on how to update
your packages.

To get the most out of the theme you should also install the |Fira| fonts.
However, this is not mandatory; \themename also works with the standard fonts.


\subsection{Installing from GitHub}

If you want to use the cutting-edge development version of \themename, you can
install it manually. Like any \LaTeX\ package, this involves four easy steps:
\begin{description}
  \item[Download the source] with a |git clone| of the
    \href{https://github.com/matze/mtheme}{\themename repository} or as a
    \href{https://github.com/matze/mtheme/archive/master.zip}{zip archive}
    of the latest development version.

  \item[Compile the style files] by running |make sty| inside the downloaded
    directory. (Or run \LaTeX{} directly on |source/metropolistheme.ins|.)

  \item[Move the resulting |*.sty| files] to the folder containing your
    presentation. To use \themename with many presentations, run
    |make install| or move the |*.sty| files to a folder in your \TeX{} path
    instead.

  \item[Use the theme for your presentation] by declaring
    |\usetheme{metropolis}| in the preamble of your Beamer document.
\end{description}

\themename uses the Make build system to offer the following installation
options for advanced users:

\begin{description}
  \item[|make sty|] builds the theme style files.
  \item[|make doc|] builds this documentation manual.
  \item[|make demo|] builds a demo presentation to test the features of
    \themename.
  \item[|make all|] builds the theme and manual.
  \item[|make clean|] removes the files generated by |make all|.
  \item[|make install|] installs the theme into your local texmf folder.
  \item[|make uninstall|] removes the theme from your local texmf folder.
\end{description}


\subsection{A Minimal Example}

The following code shows a minimal example of a Beamer presentation using
\themename.

\begin{lstlisting}
\documentclass{beamer}
\usetheme{metropolis}       % Use metropolis theme
\title{A minimal example}
\date{\today}
\author{Matthias Vogelgesang}
\institute{Centre for Modern Beamer Themes}
\begin{document}
  \maketitle
  \section{First Section}
  \begin{frame}{First Frame}
    Hello, world!
  \end{frame}
\end{document}
\end{lstlisting}


\subsection{Dependencies}

\themename depends on the |beamer| class and the following standard packages:
\begin{multicols}{3}
  \begin{itemize}
    \item |tikz|
    \item |pgfopts|
    \item |etoolbox|
    \item |calc|
    \item |ifxetex|
    \item |ifluatex|
  \end{itemize}
\end{multicols}

For best results, we recommend installing the fonts
\href{https://github.com/mozilla/Fira}{|Fira Sans|} and |Fira Mono|
and compiling with \themename using \XeLaTeX\ or \LuaTeX.
These are optional dependencies; \themename is compatible with (e.g.)
pdf\LaTeX\ and will fall back to standard fonts if |Fira Sans| or |Fira Mono|
is not installed.

The packaged name of |Fira Sans| is |Fira Sans OT| in some Linux
distributions; this case is automatically handled by \themename.


\subsection{Pandoc}

To use this theme with \href{http://johnmacfarlane.net/pandoc/}{Pandoc}-based
presentations, you can run the following command

\begin{lstlisting}
$ pandoc -t beamer --latex-engine=xelatex -V theme:metropolis -o output.pdf input.md
\end{lstlisting}


\section{Customization}

\subsection{Package options}

The theme provides a number of options, which can be set using a key=value
interface. The primary way to set options is to provide a comma-separated list
of option-value pairs when loading \themename in the preamble:
\begin{lstlisting}
\usetheme[option1=value1, option2=value2, ...]{metropolis}
\end{lstlisting}

Options can be changed at any time --- even mid-presentation! --- with the
|\metroset| macro.
\begin{lstlisting}
\metroset{option1=newvalue1, option2=newvalue2, ...}
\end{lstlisting}

The list of options is structured as shown in the following example.

\DescribeOption{option key}{list of possible values}{default}{
  A short description of the option.
}


\subsubsection{Main theme}

\DescribeOption{titleformat}%
               {regular, smallcaps, allsmallcaps, allcaps}
               {regular}{
  Changes the format of titles, subtitles, section titles, frame titles, and
  the text on ``standout'' frames. The available options produce
  Regular, \textsc{SmallCaps}, \textsc{\MakeLowercase{AllSmallCaps}}, or
  \MakeUppercase{AllCaps} titles. Please refer to
  Section~\ref{sec:titleformats} for known issues with these options.
}

\DescribeOption{titleformat plain}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Changes the format of ``standout'' frames (see |titleformat|, above).
}


\subsubsection{Inner theme}

\DescribeOption{sectionpage}{none, simple, progressbar}{progressbar}{
  Adds a slide at the start of each section (|simple|) with an optional thin
  progress bar below the section title (|progressbar|). The |none| option
  disables the section page.
}

\DescribeOption{subsectionpage}{none, simple, progressbar}{none}{
  Optionally adds a slide at the start of each subsection. If enabled with
  the |simple| or |progressbar| options, the style of the |section page| will
  be updated to match the style of the |subsection page|. Note that section
  slides and subsection slides can appear consecutively if both are enabled;
  you may want to use this option together with |sectionpage=none| depending
  on the section structure of your presentation.
}


\subsubsection{Outer theme}

\DescribeOption{numbering}{none, counter, fraction}{counter}{
  Controls whether the frame number at the bottom right of each slide is
  omitted (|none|), shown (|counter|) or displayed as a fraction of the total
  number of frames (|fraction|).
}

\DescribeOption{progressbar}{none, head, frametitle, foot}{none}{
  Optionally adds a progress bar to the top of each frame (|head|),
  the bottom of each frame (|foot|), or directly below each frame title
  (|frametitle|).
}

\subsubsection{Color theme}
\DescribeOption{block}{transparent, fill}{transparent}{
  Optionally adds a light grey background to block environments like |theorem|
  and |example|.
}

\DescribeOption{background}{dark, light}{light}{
  Provides the option to have a dark background and light foreground instead
  of the reverse.
}


\subsubsection{Font theme}

\DescribeMacro{titleformat title}
\DescribeMacro{titleformat subtitle}
\DescribeMacro{titleformat section}
\DescribeOption{titleformat frame}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Individually controls the format of titles, subtitles, section titles, and
  frame titles (see |titleformat|, above).
}


\subsection{Color Customization}

The included \themename color theme is used by default, but its colors can be
easily changed to suit your tastes. All of the theme's styles are defined in
terms of three beamer colors:
\begin{itemize}
    \item |normal text| (dark fg, light bg)
    \item |alerted text| (colored fg, should be visible against dark or light)
    \item |example text| (colored fg, should be visible against dark or light)
\end{itemize}

An easy way to customize the theme is to redefine these colors using

\begin{lstlisting}
\setbeamercolor{ ... }{ fg= ... , bg= ... }
\end{lstlisting}
in your preamble. For greater customization, you can redefine any of the other
stock beamer colors. In addition to the stock colors the theme defines a number
of \themename specific colors, which can also be redefined to your liking.

\begin{lstlisting}
\setbeamercolor{progress bar}{ ... }
\setbeamercolor{title separator}{ ... }
\setbeamercolor{progress bar in head/foot}{ ... }
\setbeamercolor{progress bar in section page}{ ... }
\end{lstlisting}


\subsection{Font Customization}

The default font for \themename is |Fira|. This can be easily changed using
the standard font selection commands of the \textsf{fontspec} package. So if
you prefer, for example, the \href{http://font.ubuntu.com}{|Ubuntu|} font family, just add the following two commands after loading the \themename theme.

\begin{lstlisting}
\setsansfont{Ubuntu}
\setmonofont{Ubuntu Mono}
\end{lstlisting}

If you are expecting to present in a large room or with an underpowered
projector, you may want to change the font to a heavier weight of Fira to
maximize readability.

\begin{lstlisting}
\setsansfont[BoldFont={Fira Sans SemiBold}]{Fira Sans Book}
\end{lstlisting}


\subsubsection{Old style figures}

The regular \textsf{fontspec} mechanism for changing glyph appearance applies
also to this theme. If you want to have old style figures in the text but
regular lined figures for math, you could add the following to your preamble:

\begin{lstlisting}
\usefonttheme{professionalfonts}   % required for mathspec
\usepackage{mathspec}
\setsansfont[BoldFont={Fira Sans},
             Numbers={OldStyle}]{Fira Sans Light}
\setmathsfont(Digits)[Numbers={Lining, Proportional}]{Fira Sans Light}
\end{lstlisting}


\subsection{Commands}

\subsubsection{Standout frames}

The \themename inner theme offers a custom frame format with large, centered
text and an inverted background --- perfect for focusing attention on
single sentence or image. To use it, add the key |standout| to the frame:

\begin{lstlisting}
\begin{frame}[standout]
    Thank you!
\end{frame}
\end{lstlisting}



\section{\texttt{pgfplots} integration}

\themename comes with a set of pre-defined pgfplots styles and a color theme
based on Paul Tol's color scheme.


\subsection{Styles}

Pass the following style keys to the axis environment to get the appropriate
effect:

\begin{macro}{mlineplot}
  Plot regular line charts with reduced axis frames, less intrusive legend and
  subdued grid.
\end{macro}
\begin{macro}{mbarplot}
  Plot vertical bar charts in a similar way as |mlineplot| but reduce grid usage.
\end{macro}
\begin{macro}{horizontal mbarplot}
  Plot horizontal bar charts.
\end{macro}
\begin{macro}{disable thousands separator}
  Helper style to remove thousands separator.
\end{macro}


\subsection{Paul Tol colors}

A good presentation uses colors that are distinct from each other as much as
possible as well as from black and white, can be discerned item under different
lighting and display environments and by color-blind viewers, while matching
well together.

In a \href{https://personal.sron.nl/~pault/colourschemes.pdf}{technical note}
for SRON, Paul Tol proposed a palette of colors satisfying these constraints.
The sub-package |pgfplotsthemetol| defines palettes for |pgfplots| charts
based on Tol's work.


\section{Tips \& Tricks}

\subsection{Backup Slides}

Speakers will often include extra slides at the end of their presentation to
refer to during audience questions. One easy way to do this is to include the
\verb|appendixnumberbeamer| package in your preamble and call \verb|\appendix| before your backup slides.

\themename will automatically turn off slide numbering and progress bars for
slides in the appendix.


\section{Known Issues}

\subsection{Title formats}
\label{sec:titleformats}

Be aware that not every font supports small caps, so the |smallcaps| or
|allsmallcaps| options may not work if you use a font other than |Fira Sans|.
In particular, the Computer Modern sans-serif typeface, which is used when
\themename is compiled with pdf\LaTeX, does not have a small-caps variant.

The title format options |allsmallcaps| and |allcaps| are quite nice from an
aesthetic point of view, but their use of |\MakeLowercase| and
|\MakeUppercase| can cause unexpected problems. For example:

\begin{itemize}
    \item Some commands, like |\\|, do not work inside |\MakeLowercase| and
    |\MakeUppercase|. (See \href{https://github.com/matze/mtheme/issues/125}
    {\#125})
    \item Only alphabetic characters are affected by |\MakeLowercase|, so
    numerals and punctuation remain at full height. This can spoil some of the
    aesthetic benefits of |allsmallcaps|. (See
    \href{https://github.com/matze/mtheme/issues/33}{\#33})
    \item |\MakeLowercase| and |\MakeUppercase| apply to math mode and
    |\scshape| does not. This can easily introduce mathematical errors that
    are hard to catch.
    \item It is impossible to typeset symbols which are encoded as uppercase
    letters in a different font. In particular, |\mathbb| and |\mathcal|
    letters will be replaced by other math glyphs. (See
    \href{https://github.com/matze/mtheme/issues/153}{\#153})
\end{itemize}

The |allsmallcaps| and |allcaps| options are safe to use if your titles contain
only alphabetic characters and do not require the expansion of any macros.


\subsection{Interactions with other color themes}

\themename can be used along with any other Beamer color theme, such as
|crane| or |seahorse|. If you wish to do this, it is usually best to include
the \themename subpackages individually so the \themename color theme is
never loaded. This will prevent conflicts between the \themename color theme
and your preferred theme.

For example, overriding the color theme as follows may not work as expected because |\usetheme{metropolis}| loads the \themename color theme, which
defines a relationship between the frametitle background and the primary
palette of the theme. Since |seahorse| assumes a different relationship
between its palettes, the result is a grey, rather than periwinkle,
frametitle background.

\begin{lstlisting}
\usetheme{metropolis}
\usecolortheme{seahorse}
\end{lstlisting}

The correct colors are chosen if the \themename outer, inner, and font themes
are loaded seperately:

\begin{lstlisting}
\useoutertheme{metropolis}
\useinnertheme{metropolis}
\usefonttheme{metropolis}
\usecolortheme{seahorse}   % or your preferred color theme
\end{lstlisting}

Please note that \themename may not use all the colors defined in your
favourite Beamer color theme. In particular, \themename does not set a
background color for the title; this will cause issues when using color themes
like |whale| which set a white foreground for the title.


\subsection{Notes on second screen}

If you use the |[show notes on second screen]| option built in to Beamer and
compile with \XeLaTeX, text on slides following the first section slide may
be rendered in white instead of the regular colour. This is due to
\href{http://tex.stackexchange.com/questions/288408/}{a bug} in Beamer
or \XeLaTeX\ itself. You can work around it either by compiling with \LuaTeX\
or by adding the following code to your preamble to reset the text color
on each slide.

\begin{lstlisting}
\makeatletter
\def\beamer@framenotesbegin{% at beginning of slide
     \usebeamercolor[fg]{normal text}
      \gdef\beamer@noteitems{}%
      \gdef\beamer@notes{}%
}
\makeatother
\end{lstlisting}


\subsection{Standout frames with labels}

Because the |standout| frame option creates a group to restrict the colour
change to a single slide, labels defined after calling |standout| will stay
local to the group. In other words, the following may result in a ``label undefined'' error.

\begin{lstlisting}
\begin{frame}[standout, label=conclusion]{Conclusion}
  Awesome slide
\end{frame}
\end{lstlisting}

To fix this problem, change the order of the keys in the frame.

\begin{lstlisting}
\begin{frame}[label=conclusion, standout]{Conclusion}
    Awesome slide
\end{frame}
\end{lstlisting}

This error can be unwittingly triggered if you export your slides from Emacs
Org mode, which automatically adds labels after frame options. Alex Branham
\href{https://github.com/matze/mtheme/issues/203}{offers} the following
solution for Org mode users, using |org-set-property|.

\begin{lstlisting}
* Start of a frame
   :PROPERTIES:
   :BEAMER_opt: label=conclusion,standout
   :END:
\end{lstlisting}


\subsection{Standout frames with Pandoc}

With Pandoc versions prior 1.17.2 it was not possible to create standout frames
because Pandoc only supported a specific list of frame attributes thus ignoring
additional attributes such as  |{.standout}|.


\section{License}

\themename is licensed under a
\href{http://creativecommons.org/licenses/by-sa/4.0/}{Creative Commons
Attribution-ShareAlike 4.0 International License}.
This means that if you change the theme and re-distribute it, you must retain
the copyright notice header and license it under the same CC-BY-SA license.
This does not affect any presentations that you create with the theme.


\section{Implementation}

\DocInput{beamerthememetropolis.dtx}
\DocInput{beamerinnerthememetropolis.dtx}
\DocInput{beamerouterthememetropolis.dtx}
\DocInput{beamerfontthememetropolis.dtx}
\DocInput{beamercolorthememetropolis.dtx}
\DocInput{pgfplotsthemetol.dtx}

\end{document}
