doc: redesign manual for moloch

doc/moloch.tex

@@ -11,6 +11,9 @@
 %% --------------------------------------------------------------------------- 
 %% Copyright 2024 Johan Larsson and contributors
 %% ---------------------------------------------------------------------------
+\PassOptionsToPackage{unicode,pdfusetitle}{hyperref}
+\PassOptionsToPackage{hyphens}{xurl}
+\PassOptionsToPackage{dvipsnames}{xcolor}
 
 \documentclass{ltxdoc}
 
@@ -18,7 +21,10 @@
 \usepackage{setspace}
 \usepackage{xspace}
 \usepackage{xurl}
-\onehalfspacing
+
+\usepackage{lmodern}
+\usepackage{microtype}
+\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
 
 \usepackage{enumitem}
 \setlist[itemize]{noitemsep}
@@ -35,8 +41,8 @@
 \lstset{%
   language=[LaTeX]{TeX},
   basicstyle=\ttfamily,
-  keywordstyle=\color{mLightBrown}\bfseries,
+  keywordstyle=\color{MidnightBlue}\bfseries,
-  commentstyle=\color{mLightGreen},
+  commentstyle=\color{Periwinkle},
   stringstyle=\color{mLightGreen},
   backgroundcolor=\color{mBackground},
   numbers=none,
@@ -58,22 +64,27 @@
   xrightmargin=0em,
   aboveskip=1em,
   belowskip=1em,
-  morekeywords={usetheme,institute,maketitle,@moloch@titleformat,%
+  morekeywords={
-                plain,setbeamercolor,molochset,setsansfont,setmonofont},
+    usetheme,
+    institute,
+    maketitle,
+    @moloch@titleformat,
+    %plain,
+    setbeamercolor,
+    molochset,
+    setsansfont,
+    setmonofont
+  },
 }
 \lstMakeShortInline|
 \usepackage{metalogo}
 
-\usepackage[colorlinks=true,
+\usepackage[colorlinks=true,linkcolor=MidnightBlue,urlcolor=MidnightBlue]{hyperref}
-            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
+    \textit{\textbf{\textcolor{JungleGreen}{#2}}}\dotfill\,#3\par
     \begingroup
     \vspace{0.5em}#4\par
     \endgroup
@@ -85,16 +96,18 @@
 \def\molochversion{0.5.0} % x-release-please-version
 
 \usepackage{readprov}
-% \ReadPackageInfos{beamerthememoloch}
 
-\title{The \themename package (v\molochversion)}
+\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
+
+\hypersetup{linkcolor=black}
 \tableofcontents
+\hypersetup{linkcolor=MidnightBlue}
 
 \section{Introduction}
 
@@ -200,7 +213,7 @@ $ pandoc -t beamer -V theme:moloch -o output.pdf input.md
 
 \section{Customization}
 
-\subsection{Package options}
+\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
@@ -221,7 +234,7 @@ The list of options is structured as shown in the following example.
   A short description of the option.
 }
 
-\subsubsection{Main theme}
+\subsubsection{Main Theme}
 
 \DescribeOption{titleformat}%
 {regular, smallcaps, allsmallcaps, allcaps}
@@ -240,7 +253,7 @@ The list of options is structured as shown in the following example.
   Changes the format of ``standout'' frames (see |titleformat|, above).
 }
 
-\subsubsection{Inner theme}
+\subsubsection{Inner Theme}
 
 \DescribeOption{sectionpage}{none, simple, progressbar}{progressbar}{
   Adds a slide at the start of each section (|simple|) with an optional thin
@@ -257,7 +270,7 @@ The list of options is structured as shown in the following example.
   on the section structure of your presentation.
 }
 
-\subsubsection{Outer theme}
+\subsubsection{Outer Theme}
 
 \DescribeOption{numbering}{none, counter, fraction}{}{
   \emph{This option is deprecated and will be removed in a future version.
@@ -273,7 +286,7 @@ The list of options is structured as shown in the following example.
   (|frametitle|).
 }
 
-\subsubsection{Color theme}
+\subsubsection{Color Theme}
 
 \DescribeOption{block}{transparent, fill}{transparent}{
   Optionally adds a light grey background to block environments like |theorem|
@@ -285,7 +298,7 @@ The list of options is structured as shown in the following example.
   of the reverse.
 }
 
-\subsubsection{Font theme}
+\subsubsection{Font Theme}
 
 \DescribeMacro{titleformat title}
 \DescribeMacro{titleformat subtitle}
@@ -333,7 +346,7 @@ For low-light situations \themename it might be helpful to use the
 
 \subsection{Commands}
 
-\subsubsection{Standout frames}
+\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
@@ -359,7 +372,7 @@ 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}
+\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
@@ -393,7 +406,7 @@ 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}
+\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
@@ -413,7 +426,7 @@ on each slide.
 \makeatother
 \end{lstlisting}
 
-\subsection{Standout frames with labels}
+\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
@@ -445,7 +458,7 @@ solution for Org mode users, using |org-set-property|.
    :END:
 \end{lstlisting}
 
-\subsection{Standout frames with Pandoc}
+\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

src/beamercolorthememoloch.dtx

@@ -23,11 +23,11 @@
 %<*package>
 % ------------------------------------------------------------------------- \fi
 %
-% \subsection{\themename color theme}
+% \subsection{\themename Color Theme}
 %
 %
 %
-% \subsubsection{Package dependencies}
+% \subsubsection{Package Dependencies}
 %    \begin{macrocode}
 \RequirePackage{pgfopts}
 %    \end{macrocode}
@@ -75,7 +75,7 @@
 %
 %
 %
-% \subsubsection{Base colors}
+% \subsubsection{Base Colors}
 %
 %    \begin{macrocode}
 \definecolor{mDarkBrown}{HTML}{604c38}
@@ -86,7 +86,7 @@
 %
 %
 %
-% \subsubsection{Base styles}
+% \subsubsection{Base Styles}
 %
 % All colors in \themename are derived from the definitions of |normal text|,
 % |alerted text|, and |example text|.
@@ -115,7 +115,7 @@
 %
 %
 %
-% \subsubsection{Derived colors}
+% \subsubsection{Derived Colors}
 %
 % The titles and structural elements (e.g. |itemize| bullets) are set in the
 % same color as |normal text|. This would ideally done by setting |normal text|
@@ -127,7 +127,8 @@
 \setbeamercolor{titlelike}{use=normal text, parent=normal text}
 \setbeamercolor{author}{use=normal text, parent=normal text}
 \setbeamercolor{date}{use=normal text, parent=normal text}
-\setbeamercolor{institute}{use=normal text, fg=normal text.fg!80!normal text.bg}
+\setbeamercolor{institute}{%
+  use=normal text, fg=normal text.fg!80!normal text.bg}
 \setbeamercolor{structure}{use=normal text, fg=normal text.fg}
 %    \end{macrocode}
 %
@@ -237,7 +238,7 @@
 %
 %
 %
-% \subsubsection{Process package options}
+% \subsubsection{Process Package Options}
 %
 %    \begin{macrocode}
 \moloch@color@setdefaults

src/beamerfontthememoloch.dtx

@@ -76,8 +76,8 @@
       \let\moloch@titleformat\lowercase%
       \setbeamerfont{title}{shape=\scshape}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat title=allsmallcaps can lead to problems%
+        Be aware that titleformat title=allsmallcaps can
-      }
+        lead to problems}
     },
   allcaps/.code={%
       \let\moloch@titleformat\uppercase%
@@ -108,15 +108,15 @@
       \let\moloch@subtitleformat\MakeLowercase%
       \setbeamerfont{subtitle}{shape=\scshape}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat subtitle=allsmallcaps can lead to problems%
+        Be aware that titleformat subtitle=allsmallcaps
-      }
+        can lead to problems}
     },
   allcaps/.code={%
       \let\moloch@subtitleformat\MakeUppercase%
       \setbeamerfont{subtitle}{shape=\normalfont}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat subtitle=allcaps can lead to problems%
+        Be aware that titleformat subtitle=allcaps can
-      }
+        lead to problems}
     },
 }
 %    \end{macrocode}
@@ -140,15 +140,15 @@
       \let\moloch@sectiontitleformat\MakeLowercase%
       \setbeamerfont{section title}{shape=\scshape}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat section=allsmallcaps can lead to problems%
+        Be aware that titleformat section=allsmallcaps
-      }
+        can lead to problems}
     },
   allcaps/.code={%
       \let\moloch@sectiontitleformat\MakeUppercase%
       \setbeamerfont{section title}{shape=\normalfont}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat section=allcaps can lead to problems%
+        Be aware that titleformat section=allcaps
-      }
+        can lead to problems}
     },
 }
 %    \end{macrocode}
@@ -172,8 +172,8 @@
       \let\moloch@frametitleformat\MakeLowercase%
       \setbeamerfont{frametitle}{shape=\scshape}%
       \PackageNote{beamerthememoloch}{%
-        Be aware that titleformat frame=allsmallcaps can lead to problems%
+        Be aware that titleformat frame=allsmallcaps
-      }
+        can lead to problems}
     },
   allcaps/.code={%
       \let\moloch@frametitleformat\MakeUppercase%

src/beamerinnerthememoloch.dtx

@@ -23,7 +23,7 @@
 %<*package>
 % ------------------------------------------------------------------------- \fi
 %
-% \subsection{\themename inner theme}
+% \subsection{\themename Inner Theme}
 %
 % A |beamer| inner theme dictates the style of the frame elements traditionally
 % set in the ``body'' of each slide. These include:
@@ -38,7 +38,7 @@
 %
 %
 %
-% \subsubsection{Package dependencies}
+% \subsubsection{Package Dependencies}
 %
 %    \begin{macrocode}
 \RequirePackage{keyval}
@@ -132,7 +132,7 @@
 %
 %
 %
-% \subsubsection{Title page}
+% \subsubsection{Title Page}
 %
 % \begin{macro}{title page}
 % Template for the title page. Each element is only typset if it is defined
@@ -143,7 +143,9 @@
   \begin{minipage}[b][\paperheight]{\textwidth}
     \null%
     \vfil%
-    \ifx\inserttitlegraphic\@empty\else\usebeamertemplate*{title graphic}\fi
+    \ifx\inserttitlegraphic\@empty%
+    \else\usebeamertemplate*{title graphic}%
+    \fi
     \ifx\inserttitle\@empty\else\usebeamertemplate*{title}\fi
     \ifx\insertsubtitle\@empty\else\usebeamertemplate*{subtitle}\fi
     \usebeamertemplate*{title separator}
@@ -276,9 +278,9 @@
 % \end{macro}
 %
 %
-% \subsubsection{Section page}
+% \subsubsection{Section Page}
 %
-% \begin{macro}{section page}
+% \begin{macro}{section Page}
 %
 %   Template for the section title slide at the beginning of each section.
 %
@@ -382,13 +384,14 @@
     \fill[fg]
     (0,0)
     rectangle
-    (\moloch@progressonsectionpage, \moloch@progressonsectionpage@linewidth);
+    (\moloch@progressonsectionpage,
+    \moloch@progressonsectionpage@linewidth);
   \end{tikzpicture}%
   \tikzexternalenable%
 }
 %    \end{macrocode}
 %
-%   The above code assumes that |\insertframenumber| is less than or equal to
+%   The code above assumes that |\insertframenumber| is less than or equal to
 %   |\inserttotalframenumber|. However, this is not true on the first compile;
 %   in the absence of an |.aux| file, |\inserttotalframenumber| defaults to 1.
 %   This behaviour could cause fatal errors for long presentations, as
@@ -403,7 +406,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \subsubsection{Lists and floats}
+% \subsubsection{Lists and Floats}
 %
 %    \begin{macrocode}
 \setbeamertemplate{itemize item}{\(\bullet\)}
@@ -426,7 +429,7 @@
 %
 %
 %
-% \subsubsection{Text and spacing settings}
+% \subsubsection{Text and Spacing Settings}
 %
 %
 % By default, Beamer frames offer the |c| option to \textit{almost} vertically
@@ -448,7 +451,7 @@
 %
 %
 %
-% \subsubsection{Standout frames}
+% \subsubsection{Standout Frames}
 %
 % \themename offers a custom frame format with large, centered text and an
 % inverted background. To use it, add the key |standout| to the frame:
@@ -468,7 +471,8 @@
   \booltrue{moloch@standout}
   \begingroup
   \setkeys{beamerframe}{c}
-  \ifbool{moloch@enableStandoutNumbering}{}{\setkeys{beamerframe}{noframenumbering}}
+  \ifbool{moloch@enableStandoutNumbering}{}{%
+    \setkeys{beamerframe}{noframenumbering}}
   \ifbeamercolorempty[bg]{palette primary}{
     \setbeamercolor{background canvas}{
       use=palette primary,
@@ -522,7 +526,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \subsubsection{Process package options}
+% \subsubsection{Process Package Options}
 %
 %    \begin{macrocode}
 \moloch@inner@setdefaults

src/beamerouterthememoloch.dtx

@@ -171,7 +171,9 @@
 }
 
 \newcommand{\moloch@frametitlestrut@end}{%
-  \vphantom{\rule[-\moloch@frametitle@padding]{0pt}{\moloch@frametitle@padding}}
+  \vphantom{%
+    \rule[-\moloch@frametitle@padding]{0pt}{\moloch@frametitle@padding}%
+  }
 }
 \defbeamertemplate{frametitle}{plain}{%
   \nointerlineskip%
@@ -198,7 +200,8 @@
     \moloch@frametitlestrut@end%
   \end{beamercolorbox}%
 }
-\setbeamertemplate{frametitle continuation}{\romannumeral\insertcontinuationcount}
+\setbeamertemplate{frametitle continuation}{%
+  \romannumeral\insertcontinuationcount}
 %    \end{macrocode}
 % \end{macro}
 %

src/beamerthememoloch.dtx

@@ -21,7 +21,7 @@
 %<*package>
 % ------------------------------------------------------------------------- \fi
 %
-% \subsection{\themename parent theme}
+% \subsection{\themename Parent Theme}
 %
 % The primary job of this package is to load the component sub-packages of the
 % \themename theme and route the theme options accordingly. It also
@@ -29,7 +29,7 @@
 %
 %
 %
-% \subsubsection{Package dependencies}
+% \subsubsection{Package Dependencies}
 %
 %    \begin{macrocode}
 \RequirePackage{pgfopts}
@@ -117,7 +117,7 @@
 \providecommand{\mmzUnmemoizable}{}
 %    \end{macrocode}
 %
-% \subsubsection{Component sub-packages}
+% \subsubsection{Component Sub-Packages}
 %
 % Having processed the options, we can now load the component sub-packages of
 % the theme.
@@ -129,7 +129,7 @@
 \usefonttheme{moloch}
 %    \end{macrocode}
 %
-% \subsubsection{Custom commands}
+% \subsubsection{Custom Commands}
 %
 % The parent theme defines custom commands as their proper usage may depend
 % on multiple sub-packages.
@@ -150,7 +150,7 @@
 %
 %
 %
-% \subsubsection{Process package options}
+% \subsubsection{Process Package Options}
 %
 %    \begin{macrocode}
 \moloch@setdefaults