Merge pull request #195 from rchurchley/documentation

Documentation updates

doc/metropolistheme.dtx

@@ -125,6 +125,7 @@
                 plain,setbeamercolor,metroset,setsansfont,setmonofont},
 }
 \lstMakeShortInline|
+\usepackage{metalogo}
 
 \usepackage[colorlinks=true,
             linkcolor=mLightBrown,
@@ -173,7 +174,7 @@ 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.
+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.
 
@@ -188,26 +189,36 @@ the theme even better, please get in touch there. The
 
 \subsection{Installing from CTAN}
 
-For the regular user it is recommended to install \themename from
+For most users, we recommend installing \themename from
-\href{https://www.ctan.org}{CTAN}. In case you keep your \TeX\ distribution
+\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. For  \TeX\ Live (or Mac\TeX\ on OS X)
+not, you need to update your packages. If your distribution is \TeX\ Live
-the following command updates all packages.
+(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.
-Yet this is not mandatory. \themename also works with the standard fonts.
+However, 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:
+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
@@ -234,20 +245,13 @@ options for advanced users:
   \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 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.
-  \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
@@ -286,9 +290,9 @@ The following code shows a minimal example of a Beamer presentation using
 
 For best results, we recommend installing the fonts
 \href{https://github.com/mozilla/Fira}{|Fira Sans|} and |Fira Mono|
-and compiling with \themename using Xe\LaTeX{} or Lua\TeX{}.
+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|
+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
@@ -335,16 +339,16 @@ The list of options is structured as shown in the following example.
                {regular, smallcaps, allsmallcaps, allcaps}
                {regular}{
   Changes the format of titles, subtitles, section titles, frame titles, and
-  the text on standout ``plain'' frames. The available options produce
+  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}%
+\DescribeOption{titleformat plain}%
                {regular, smallcaps, allsmallcaps, allcaps}%
                {regular}{
-  Changes the format of standout ``plain'' frames (see |titleformat|, above).
+  Changes the format of ``standout'' frames (see |titleformat|, above).
 }
 
 
@@ -359,7 +363,10 @@ The list of options is structured as shown in the following example.
 \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|.
+  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.
 }
 
 
@@ -391,10 +398,10 @@ The list of options is structured as shown in the following example.
 
 \subsubsection{Font theme}
 
-\DescribeMacro{titleformat-title}
+\DescribeMacro{titleformat title}
-\DescribeMacro{titleformat-subtitle}
+\DescribeMacro{titleformat subtitle}
-\DescribeMacro{titeformat-section}
+\DescribeMacro{titeformat section}
-\DescribeOption{titleformat-frame}%
+\DescribeOption{titleformat frame}%
                {regular, smallcaps, allsmallcaps, allcaps}%
                {regular}{
   Individually controls the format of titles, subtitles, section titles, and
@@ -441,6 +448,14 @@ you prefer, for example, the \href{http://font.ubuntu.com}{|Ubuntu|} font family
 \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}
 
@@ -594,6 +609,27 @@ 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}
+
+
 \section{License}
 
 \themename is licensed under a

source/beamercolorthememetropolis.dtx

@@ -10,16 +10,10 @@
 % International License (https://creativecommons.org/licenses/by-sa/4.0/).
 % ------------------------------------------------------------------------- \fi
 % \iffalse
-%<driver> \ProvidesFile{beamercolorthememetropolis.dtx}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamercolorthememetropolis}[2016/02/21 Metropolis color theme]
+\ProvidesPackage{beamercolorthememetropolis}[2016/03/08 Metropolis color theme]
 %</package>
-%<driver> \documentclass{ltxdoc}
-%<driver> \usepackage{beamercolorthememetropolis}
-%<driver> \begin{document}
-%<driver> \DocInput{beamercolorthememetropolis.dtx}
-%<driver> \end{document}
 % \fi
 % \CheckSum{0}
 % \StopEventually{}

source/beamerfontthememetropolis.dtx

@@ -10,16 +10,10 @@
 % International License (https://creativecommons.org/licenses/by-sa/4.0/).
 % ------------------------------------------------------------------------- \fi
 % \iffalse
-%<driver> \ProvidesFile{beamerfontthememetropolis.dtx}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerfontthememetropolis}[2016/02/21 Metropolis font theme]
+\ProvidesPackage{beamerfontthememetropolis}[2016/03/08 Metropolis font theme]
 %</package>
-%<driver> \documentclass{ltxdoc}
-%<driver> \usepackage{beamerfontthememetropolis}
-%<driver> \begin{document}
-%<driver> \DocInput{beamerfontthememetropolis.dtx}
-%<driver> \end{document}
 % \fi
 % \CheckSum{0}
 % \StopEventually{}

source/beamerinnerthememetropolis.dtx

@@ -10,16 +10,10 @@
 % International License (https://creativecommons.org/licenses/by-sa/4.0/).
 % ------------------------------------------------------------------------- \fi
 % \iffalse
-%<driver> \ProvidesFile{beamerinnerthememetropolis.dtx}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerinnerthememetropolis}[2016/02/21 Metropolis inner theme]
+\ProvidesPackage{beamerinnerthememetropolis}[2016/03/08 Metropolis inner theme]
 %</package>
-%<driver> \documentclass{ltxdoc}
-%<driver> \usepackage{beamerinnerthememetropolis}
-%<driver> \begin{document}
-%<driver> \DocInput{beamerinnerthememetropolis.dtx}
-%<driver> \end{document}
 % \fi
 % \CheckSum{0}
 % \StopEventually{}
@@ -397,9 +391,6 @@
 %    To achieve the correct spacing for |alertblock|s and |exampleblock|s
 %    as well as for normal blocks, we have to begin the |beamercolorbox|
 %    differently based on whether |block title| has an empty background.
-%    (We assume that either all or none of |block title|,
-%    |block title alerted|, and |block title example| have an empty
-%    background).
 %
 %    If the |block title| background is empty, or the user has explicitly
 %    removed the background from (e.g.) |block title alerted|, we just need to

source/beamerouterthememetropolis.dtx

@@ -10,16 +10,10 @@
 % International License (https://creativecommons.org/licenses/by-sa/4.0/).
 % ------------------------------------------------------------------------- \fi
 % \iffalse
-%<driver> \ProvidesFile{beamerouterthememetropolis.dtx}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerouterthememetropolis}[2016/02/21 Metropolis outer theme]
+\ProvidesPackage{beamerouterthememetropolis}[2016/03/08 Metropolis outer theme]
 %</package>
-%<driver> \documentclass{ltxdoc}
-%<driver> \usepackage{beamerouterthememetropolis}
-%<driver> \begin{document}
-%<driver> \DocInput{beamerouterthememetropolis.dtx}
-%<driver> \end{document}
 % \fi
 % \CheckSum{0}
 % \StopEventually{}

source/beamerthememetropolis.dtx

@@ -10,17 +10,11 @@
 % International License (https://creativecommons.org/licenses/by-sa/4.0/).
 % ------------------------------------------------------------------------- \fi
 % \iffalse
-%<driver> \ProvidesFile{beamerthememetropolis.dtx}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{beamerthememetropolis}
-  [2016/02/21 v1.1 Metropolis Beamer theme]
+  [2016/03/08 v1.1 Metropolis Beamer theme]
 %</package>
-%<driver> \documentclass{ltxdoc}
-%<driver> \usepackage{beamerthememetropolis}
-%<driver> \begin{document}
-%<driver> \DocInput{beamerthememetropolis.dtx}
-%<driver> \end{document}
 % \fi
 % \CheckSum{0}
 % \StopEventually{}