%% ---------------------------------------------------------------------------
%% 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/).
%% --------------------------------------------------------------------------- 
%% Copyright 2024 Johan Larsson and contributors
%% ---------------------------------------------------------------------------

\documentclass{ltxdoc}

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

\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,@moloch@titleformat,%
                plain,setbeamercolor,molochset,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}{\textsf{moloch}\xspace}

\def\molochversion{0.5.0} % x-release-please-version

\usepackage{readprov}
% \ReadPackageInfos{beamerthememoloch}

\title{The \themename package (v\molochversion)}
\author{Johan Larsson \and Matthias Vogelgesang\footnote{Matthias wrote the original version of this manual for the Metropolis theme, which has since been modified by Johan Larsson.}}
\date{\today}

\begin{document}

\maketitle
\tableofcontents


\section{Introduction}


Beamer is a great 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.

\themename's codebase is maintained at \url{https://github.com/jolars/moloch}.
If you have any issues, find mistakes in the manual or want to help make
the theme even better, please get in touch there.

\themename is a fork of the popular Metropolis theme by Matthias Vogelgesang.
The motivation for the fork was to fix some longstanding bugs in Metropolis
and also simplify the codebase to make it easier to maintain and less
fragile to changes in the underlying Beamer code.

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

\subsection{Installing from Source}

If you want to use the development version of \themename, you can
install it manually. You only need a recent \LaTeX\ distribution
which includes \textbf{l3build}. Then simply follow the steps below.
\begin{description}
  \item[Download the source] with a |git clone| of
        \url{https://github.com/jolars/moloch}

  \item[Install the package] by running |l3build install| inside the downloaded
        directory.
\end{description}

\subsection{A Minimal Example}

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

\begin{lstlisting}
\documentclass{beamer}
\usetheme{moloch}
\title{A Minimal Example}
\date{\today}
\author{Johan Larsson}
\institute{Some University}
\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|
  \end{itemize}
\end{multicols}

\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 -V theme:moloch -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, ...]{moloch}
\end{lstlisting}

Options can be changed at any time---even mid-presentation---with the
|\molochset| macro.
\begin{lstlisting}
\molochset{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. Note that these commands do not
  affect math and numbers, so may not work as you expect if your titles
  contain these.
}

\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}{}{
  \emph{This option is deprecated and will be removed in a future version.
    Please use Beamer's |page number in head/foot| template instead.}
  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}

For low-light situations \themename it might be helpful to use the
|moloch-highcontrast| color theme. It is enabled like any other color theme:

\begin{lstlisting}
\usecolortheme{moloch-highcontrast}
\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{Known Issues}

\subsection{Title Formats}

Be aware that not every font supports small caps, so the |smallcaps| or
|allsmallcaps| options may not work for all fonts.
In particular, the Computer Modern sans-serif typeface, which is used
by default when \themename is compiled with pdf\LaTeX, does not have a
small-caps variant.

Note that title format options |allsmallcaps| and |allcaps| do not 
affect the sizes of numerals, punctuation, and math symbol, and are 
probably best avoided if your titles contain these characters.

\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{moloch}| 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{moloch}
\usecolortheme{seahorse}
\end{lstlisting}

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

\begin{lstlisting}
\useoutertheme{moloch}
\useinnertheme{moloch}
\usefonttheme{moloch}
\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 \verb+[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 to 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{beamerthememoloch.dtx}
\DocInput{beamerinnerthememoloch.dtx}
\DocInput{beamerouterthememoloch.dtx}
\DocInput{beamerfontthememoloch.dtx}
\DocInput{beamercolorthememoloch.dtx}

\end{document}