%% ---------------------------------------------------------------------------
%% 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{\iffontsexist}[3]{%
    \setcounter{fontsnotfound}{0}%
    \expandafter\forcsvlist\expandafter%
    \checkfont\expandafter{#1}%
    \ifnum\value{fontsnotfound}=0%
      #2%
    \else%
      #3%
    \fi%
  }
  \iffontsexist{Fira Sans Light,%
                Fira Sans Light Italic,%
                Fira Sans,%
                Fira Sans Italic}{%
    \setmainfont[BoldFont={Fira Sans}]{Fira Sans Light}%
  }{%
    \iffontsexist{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.%
      }
    }
  }
  \iffontsexist{Fira Mono, Fira Mono Bold}{%
    \setmonofont{Fira Mono}%
  }{%
    \iffontsexist{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[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}

\GetFileInfo{beamerthememetropolis.dtx}
\title{Modern Beamer Presentations with the \themename package}
\author{Matthias Vogelgesang \\ \url{matthias.vogelgesang@gmail.com}}
\date{v1.0 -- 2015/12/04}

\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 is
now overused and can be a little cluttered, and 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 Xe\LaTeX{} 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 the regular user it is recommended to install \themename from
\href{https://www.ctan.org}{CTAN}. In case 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. For  \TeX\ Live (or Mac\TeX\ on OS X) the
following command updates all packages.

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

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. Yet this
is not mandatory. \themename also works with the standard fonts.

\subsection{Installing from GitHub}

Installing \themename, like any Beamer theme, 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, manual, and demo presentation.
  \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.
  \item[|make ctan|] creates a package for CTAN distribution.
\end{description}

\subsection{Installing the Debian Package}
As an alternative users of Debian or Ubuntu can also install this
\href{https://launchpad.net/\%7Eedd/+archive/ubuntu/misc/+files/latex-mtheme_0.1.0vidid1_all.deb}{.deb package}
containing the theme files as well as the Fira Sans font files.

\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}

\begin{itemize}
  \item TikZ
  \item XeLaTeX or LuaTeX
  \item \href{https://github.com/mozilla/Fira}{Fira Sans} and Mono font
\end{itemize}

The |Fira Sans| font is not a hard dependency. \themename will try to load the
font and use it if it is installed, but if not it will just use the standard
font. Depending on the Linux distribution, the packaged name of |Fira Sans|
might be |Fira Sans OT| instead of |Fira Sans|. \themename will check for this
name too.

\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. The options use a key=value interface.
So every option is controlled by a key its value. To use an option you can
either provide a comma separated list of options when invoking
\textsc{metropolis} in the preamble of the presentation.
\begin{lstlisting}
\usetheme[<key=value list>]{metropolis}
\end{lstlisting}
Or you can set them at any time with the |\metroset| macro.
\begin{lstlisting}
\metroset{<key=value list>}
\end{lstlisting}
To set an option on a specific sub-package only you have to add the
corresponding prefix (inner, outer, color), e.g.
\begin{lstlisting}
\metroset{inner/block=fill}
\end{lstlisting}
The list of options is structured as shown in the following example.

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

Although the options are grouped into the corresponding packages every option
can and in most cases should be set on the main theme directly. If an option
is listed in multiple sub-packages, setting it on the main theme will set the
option on every sub-package accordingly.

\subsubsection{Main theme}
\DescribeOption{titleformat}%
               {regular, smallcaps, allsmallcaps, allcaps}
               {regular}{
  Shortcut option to change the titleformat of all titles together. Please
  refer to section \ref{sec:titleformats} for known issues.
}

\DescribeOption{titleformat plain}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Control the titleformat of the plain title. Please refer to section
  \ref{sec:titleformats} for known issues.
}

\subsubsection{Inner theme}
\DescribeOption{block}{transparent, fill}{transparent}{
  This option controls the block background. It can either be filled with a
  light grey or be transparent.
}

\DescribeOption{sectionpage}{none, simple, progressbar}{progressbar}{
  Disable section pages at all, typeset centered section title or add a thin
  progress bar below the centered section title.
}

\DescribeOption{titleformat title}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Control the titleformat of the title. Please refer to section
  \ref{sec:titleformats} for known issues.
}

\DescribeOption{titleformat subtitle}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Control the titleformat of the subtitle. Please refer to section
  \ref{sec:titleformats} for known issues.
}

\DescribeOption{titleformat section}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Control the titleformat of the section title. Please refer to section
  \ref{sec:titleformats} for known issues.
}

\subsubsection{Outer theme}
\DescribeOption{numbering}{none, counter, fraction}{counter}{
  In the bottom right corner of each frame the current frame number is
  displayed. This can be disabled or the total framenumber can be added
  additionally.
}

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

\DescribeOption{titleformat frame}%
               {regular, smallcaps, allsmallcaps, allcaps}%
               {regular}{
  Control the titleformat of the frame title. Please refer to section
  \ref{sec:titleformats} for known issues.
}

\subsubsection{Color theme}
\DescribeOption{block}{transparent, fill}{transparent}{
  This option controls the block background. It can either be filled with a
  light grey or be transparent.
}

\DescribeOption{background}{dark, light}{light}{
  This option defines whether the background shall be dark and the foreground
  be light or vice versa.
}

\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|. Yet this can be easily changed using
the standard font selection commands of the \textsf{fontspec} package. So if
you for example prefer 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}


\subsubsection{Old style figures}

The regular \textsf{fontspec} mechanism for changing glyph appearance applies
also to this theme. In case you want to have old style figures in the text but
regular lined figures for math, you have to 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}

\begin{macro}{\plain}
The \lstinline|\plain{title=[]}{<body>}| command sets a slide in with a plain
dark background, which can be useful to focus attention on a single sentence
or image.
\end{macro}

\subsection{Paul Tol's colors: a \texttt{pgfplots} theme}

A good presentation uses colors that are

\begin{itemize}
  \item distinct from each other as much as possible, and
  \item distinct from black and white,
  \item under many different lighting and display environments, and
  \item to color-blind viewers,
  \item all while matching well together.
\end{itemize}

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. Use the |mlineplot| key to plot line data and |mbarplot|
or horizontal |mbarplot| to plot bar charts.


\section{Known Issues}

\subsection{Titleformats}
\label{sec:titleformats}
If you want to use either |smallcaps| or |allsmallcaps| be aware that not
every font supports small caps. So make sure the font you are using does.

|allsmallcaps| and |allcaps| are quite nice from an aesthetic point of view,
but they introduce some issues by using |\MakeLowercase| and |\MakeUppercase|,
respectively.

\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}

\subsection{Plain Frame}
The |\plain| command does not work if you override the \themename color theme
with the default beamer color theme |fly|.

\section{License}

The theme itself 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 the
presentation 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}