From 81c21d106eeb6664e1fe6b1150cce32ff3546f20 Mon Sep 17 00:00:00 2001
From: LogCreative <logcreative@outlook.com>
Date: Wed, 17 Jan 2024 00:22:47 +0800
Subject: [PATCH] feat: new options `bg` and `fg`

---
 testfiles/block.lvt                          |  3 +-
 testfiles/cascade.lvt                        |  3 +-
 testfiles/dual.lvt                           |  3 +-
 testfiles/iiiblock.lvt                       |  3 +-
 testfiles/img.lvt                            |  4 +-
 testfiles/progressbar.lvt                    |  3 +-
 testfiles/secblock.lvt                       |  3 +-
 texmf/doc/latex/presenter/presenter-code.tex | 54 +++++++++----
 texmf/source/latex/presenter/presenter.dtx   | 83 +++++++++++++++++++-
 texmf/tex/latex/presenter/presenter.cls      | 10 +++
 texmf/tex/latex/presenter/presenter.sty      | 13 +++
 11 files changed, 151 insertions(+), 31 deletions(-)

diff --git a/testfiles/block.lvt b/testfiles/block.lvt
index abc23ef..07bac72 100644
--- a/testfiles/block.lvt
+++ b/testfiles/block.lvt
@@ -1,7 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
-\LoadPresenterBackground{block}
+\documentclass[bg=block]{presenter}
 \EditPresenterBackground{headline}{stroke=true}
 \begin{document}
 
diff --git a/testfiles/cascade.lvt b/testfiles/cascade.lvt
index 8759a6a..d9913f5 100644
--- a/testfiles/cascade.lvt
+++ b/testfiles/cascade.lvt
@@ -1,7 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
-\LoadPresenterForeground{cascade}
+\documentclass[fg=cascade]{presenter}
 \EditPresenterForeground{headline}{parent-separator={\quad $\rightarrow$\quad}}
 \title{Cascade Style}
 \author{Your Name}
diff --git a/testfiles/dual.lvt b/testfiles/dual.lvt
index 6a5109d..f0aa45c 100644
--- a/testfiles/dual.lvt
+++ b/testfiles/dual.lvt
@@ -1,7 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
-\LoadPresenterForeground{dual}
+\documentclass[fg=dual]{presenter}
 \title{Dual Style}
 \geometry{headheight=1.8cm,top=2.3cm}
 \begin{document}
diff --git a/testfiles/iiiblock.lvt b/testfiles/iiiblock.lvt
index d9270cc..b8c801d 100644
--- a/testfiles/iiiblock.lvt
+++ b/testfiles/iiiblock.lvt
@@ -1,8 +1,7 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
+\documentclass[bg=iiiblock]{presenter}
 \usepackage{xcolor}
-\LoadPresenterBackground{iiiblock}
 \EditPresenterBackground{headline}{fill-color=blue!70!green}
 \EditPresenterForeground{headline}{style={\Large\color{white}}}
 \begin{document}
diff --git a/testfiles/img.lvt b/testfiles/img.lvt
index 298f875..3d73afc 100644
--- a/testfiles/img.lvt
+++ b/testfiles/img.lvt
@@ -1,9 +1,7 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
+\documentclass[bg=img, fg=img]{presenter}
 \usepackage{mwe}
-\LoadPresenterBackground{img}
-\LoadPresenterForeground{img}
 \begin{document}
 \paragraph{center image}
 \EditPresenterBackground{canvas}{
diff --git a/testfiles/progressbar.lvt b/testfiles/progressbar.lvt
index 1d33bc1..bfeaaac 100644
--- a/testfiles/progressbar.lvt
+++ b/testfiles/progressbar.lvt
@@ -1,7 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass{presenter}
-\LoadPresenterBackground{progressbar}
+\documentclass[bg=progressbar]{presenter}
 \makeatletter
 \gdef\@abspage@last{6}  % assume it is the second run
 \makeatother
diff --git a/testfiles/secblock.lvt b/testfiles/secblock.lvt
index 933ead2..c9a7fce 100644
--- a/testfiles/secblock.lvt
+++ b/testfiles/secblock.lvt
@@ -1,7 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass[base=report]{presenter}
-\LoadPresenterBackground{secblock}
+\documentclass[base=report, bg=secblock]{presenter}
 \begin{document}
 
 Testing the first empty sectioning page.
diff --git a/texmf/doc/latex/presenter/presenter-code.tex b/texmf/doc/latex/presenter/presenter-code.tex
index 1a68b3a..fd34c1b 100644
--- a/texmf/doc/latex/presenter/presenter-code.tex
+++ b/texmf/doc/latex/presenter/presenter-code.tex
@@ -55,6 +55,11 @@
 \renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.7em}}
 \makeatother
 
+\newrobustcmd\rexptarget{%
+  \AddLineBeginMainAux{\csgdef{Codedoc@rexpstar}{}}%
+  \csname Hy@raisedlink\endcsname{\hypertarget{rexpstar}{}}}
+\newrobustcmd\rexpstar{\hyperlink{rexpstar}{\ding{73}}}
+
 \begin{document}
 
 \maketitle
@@ -107,7 +112,7 @@
 \section{Introduction}
 
 \presenter{} is a document class (or a package) to create presentations from
-regular \LaTeX{} documents without many modifications, \textit{i.e.} present
+regular \LaTeX{} documents without many modifications, \textit{i.e.}, present
 your \LaTeX{} document in a screen-friendly way.
 
 \presenter{} won't need any additional \env{frame} or \env{slide} environments
@@ -240,21 +245,9 @@ \section{Basics}
 
 \section{Options}
 
-\begin{function}[added=2024-01-14]{base, base-options}
-  Set the \meta{base} document class to be used with \meta{base-options} comma 
-  list. The default is \cls{article} base document class with empty options.
-  
-  You should always set \meta{base} first if you want to use a different base
-  document class other than \cls{article}. And always surround your
-  \meta{base-options} comma list with braces (\verb"{}") especially if you want
-  to pass multiple options to the \meta{base} document class.
-
-  If you want to use \tn{chapter} level, you could use \cls{report} document
-  class as the base like \verb"\documentclass[base=report,base-options={}]{presenter}".
-\end{function}
-
 \begin{texnote}
-  If you want to customize the loading of the \presenter{} code,
+  Other than loading the document class \cls{presenter} shown previously,
+  if you want to customize the loading of the \presenter{} code,
   you could use the package \pkg{presenter} instead.
 
 \begin{center}
@@ -272,8 +265,38 @@ \section{Options}
   \previewtest{package}
 \end{minipage}
 \end{center}
+
+In the following section, the option with \rexptarget\rexpstar{} represents that
+it is only available as a document class option,
+\emph{i.e.}, not available as a package option.
+
 \end{texnote}
 
+\begin{function}[rEXP,added=2024-01-14]{base, base-options}
+  Set the \meta{base} document class to be used with \meta{base-options} comma 
+  list. The default is \cls{article} base document class with empty options.
+  
+  You should always set \meta{base} first if you want to use a different base
+  document class other than \cls{article}. And always surround your
+  \meta{base-options} comma list with braces (\verb"{}") especially if you want
+  to pass multiple options to the \meta{base} document class.
+
+  If you want to use \tn{chapter} level, you could use \cls{report} document
+  class as the base like \verb"\documentclass[base=report,base-options={}]{presenter}".
+\end{function}
+
+\begin{function}[added=2024-01-16]{bg, fg}
+  Set the initial background (\verb"bg") and foreground (\verb"fg") templates to
+  be loaded. \pkg{default} background and \pkg{default} foreground templates are
+  loaded by default and before the assigned templates are loaded.
+  
+  The name choices can be viewed in Section \ref{sec:pretbg} and Section
+  \ref{sec:pretfg} respectively.
+  For advanced template loading, you could ignore these options and see the
+  commands \cs{LoadPresenterBackground} and \cs{LoadPresenterForeground} in
+  page \pageref{sec:loadtpl}.
+\end{function}
+
 \section{Templates}
 
 \subsection{Decomposition}
@@ -335,6 +358,7 @@ \subsection{Decomposition}
 {\texttt{testfiles/}} folder for the code example of using these templates.
 
 \subsection{Load Templates}
+\label{sec:loadtpl}
 
 \begin{function}[added=2023-03-17,updated=2023-07-14]{\LoadPresenterBackground}
   \begin{syntax}
diff --git a/texmf/source/latex/presenter/presenter.dtx b/texmf/source/latex/presenter/presenter.dtx
index 395487d..0fdedee 100644
--- a/texmf/source/latex/presenter/presenter.dtx
+++ b/texmf/source/latex/presenter/presenter.dtx
@@ -56,6 +56,14 @@
 % to avoid the unwanted space token in the options.
 % \end{variable}
 %
+% \begin{variable}{\l_@@_bg_tl, \l_@@_fg_tl}
+% Background and foreground template selections.
+%    \begin{macrocode}
+\tl_new:N \l_@@_bg_tl
+\tl_new:N \l_@@_fg_tl
+%    \end{macrocode}
+% \end{variable}
+%
 % Declare keys for the class with family name \verb"pretcls" to avoid the
 % default family name \verb"presenter" which may conflict the package with the
 % same name.
@@ -85,6 +93,22 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{bg}
+% The background template to be initially loaded.
+%    \begin{macrocode}
+  bg.tl_gset:N = \l_@@_bg_tl,
+  bg.initial:n = default,
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{fg}
+% The foreground template to be initially loaded.
+%    \begin{macrocode}
+  fg.tl_gset:N = \l_@@_fg_tl,
+  fg.initial:n = default,
+%    \end{macrocode}
+% \end{macro}
+%
 %    \begin{macrocode}
 }
 %    \end{macrocode}
@@ -130,6 +154,14 @@
 % options raised by the latter one.
 % \end{texnote}
 %
+% Pass the initial background and foreground template to the package.
+%    \begin{macrocode}
+\PassOptionsToPackage {
+  bg = \l_@@_bg_tl,
+  fg = \l_@@_fg_tl
+} { presenter }
+%    \end{macrocode}
+%
 % Load \cls{presenter} main package.
 %    \begin{macrocode}
 \RequirePackage { presenter }
@@ -152,6 +184,43 @@
 %<@@=pret>
 %    \end{macrocode}
 %
+% \begin{variable}{\l_@@_bg_tl, \l_@@_fg_tl}
+% Background and foreground template selections.
+%    \begin{macrocode}
+\tl_new:N \l_@@_bg_tl
+\tl_new:N \l_@@_fg_tl
+%    \end{macrocode}
+% \end{variable}
+%
+%    \begin{macrocode}
+\DeclareKeys [ pret ] {
+%    \end{macrocode}
+%
+% \begin{macro}{bg}
+% The background template to be initially loaded.
+%    \begin{macrocode}
+  bg.tl_gset:N = \l_@@_bg_tl,
+  bg.initial:n = default,
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{fg}
+% The foreground template to be initially loaded.
+%    \begin{macrocode}
+  fg.tl_gset:N = \l_@@_fg_tl,
+  fg.initial:n = default,
+%    \end{macrocode}
+% \end{macro}
+%
+%    \begin{macrocode}
+}
+%    \end{macrocode}
+%
+% Process the package options.
+%    \begin{macrocode}
+\ProcessKeyOptions [ pret ]
+%    \end{macrocode}
+%
 % When using \pkg{hyperref} package, the internal link will jump to the whole
 % page (fits the page to the window), which confirms the behavior as a slide.
 % TODO: It seems that \cs{AtEndOfPackage} is not available for \pkg{hyperref}.
@@ -202,12 +271,24 @@
 %    \end{macrocode}
 %
 % One could only load the template in the preamble.
-% It is too heavy to load all the templates. Load \pkg{default} template as base.
+% It is too heavy to load all the templates.
+% Load \pkg{default} template as base
+% which is required to declare all components used by \presenter{}.
 %    \begin{macrocode}
 \LoadPresenterBackground { default }
 \LoadPresenterForeground { default }
 %    \end{macrocode}
 %
+% Then load the initial templates set by the user.
+% They will override some default components.
+% \presenter{} will not load the \pkg{default} template twice.
+%    \begin{macrocode}
+\tl_if_eq:NnF \l_@@_bg_tl { default }
+  { \LoadPresenterBackground { \l_@@_bg_tl } }
+\tl_if_eq:NnF \l_@@_fg_tl { default }
+  { \LoadPresenterForeground { \l_@@_fg_tl } }
+%    \end{macrocode}
+%
 % Introduce \pkg{xpatch} for patching command by searching the query.
 %    \begin{macrocode}
 \RequirePackage { xpatch }
diff --git a/texmf/tex/latex/presenter/presenter.cls b/texmf/tex/latex/presenter/presenter.cls
index c4e9efa..3481eff 100644
--- a/texmf/tex/latex/presenter/presenter.cls
+++ b/texmf/tex/latex/presenter/presenter.cls
@@ -27,11 +27,17 @@
   {A LaTeX presentation framework with seamless migration (class)}
 \tl_new:N \l__pretcls_base_tl
 \clist_new:N \l__pretcls_base_options_clist
+\tl_new:N \l__pretcls_bg_tl
+\tl_new:N \l__pretcls_fg_tl
 \DeclareKeys [ pretcls ] {
   base.tl_gset:N = \l__pretcls_base_tl,
   base.initial:n = article,
   base-options.clist_gset:N = \l__pretcls_base_options_clist,
   base-options.initial:n = ,
+  bg.tl_gset:N = \l__pretcls_bg_tl,
+  bg.initial:n = default,
+  fg.tl_gset:N = \l__pretcls_fg_tl,
+  fg.initial:n = default,
 }
 \DeclareUnknownKeyHandler [ pretcls ] {
   \PassOptionsToClass { \CurrentOption } { \l__pretcls_base_tl }
@@ -39,6 +45,10 @@
 \ProcessKeyOptions [ pretcls ]
 \PassOptionsToClass { \l__pretcls_base_options_clist } { \l__pretcls_base_tl }
 \LoadClass { \l__pretcls_base_tl }
+\PassOptionsToPackage {
+  bg = \l__pretcls_bg_tl,
+  fg = \l__pretcls_fg_tl
+} { presenter }
 \RequirePackage { presenter }
 \endinput
 %%
diff --git a/texmf/tex/latex/presenter/presenter.sty b/texmf/tex/latex/presenter/presenter.sty
index f93bbc9..d17c866 100644
--- a/texmf/tex/latex/presenter/presenter.sty
+++ b/texmf/tex/latex/presenter/presenter.sty
@@ -25,6 +25,15 @@
   {presenter}
   {2024-01-14}{0.7.1}
   {A LaTeX presentation framework with seamless migration (package)}
+\tl_new:N \l__pret_bg_tl
+\tl_new:N \l__pret_fg_tl
+\DeclareKeys [ pret ] {
+  bg.tl_gset:N = \l__pret_bg_tl,
+  bg.initial:n = default,
+  fg.tl_gset:N = \l__pret_fg_tl,
+  fg.initial:n = default,
+}
+\ProcessKeyOptions [ pret ]
 \IfPackageLoadedTF { hyperref }
   { \hypersetup { pdfview = Fit } }
   { \PassOptionsToPackage { pdfview = Fit } { hyperref } }
@@ -45,6 +54,10 @@
 \RequirePackage { prettpl }
 \LoadPresenterBackground { default }
 \LoadPresenterForeground { default }
+\tl_if_eq:NnF \l__pret_bg_tl { default }
+  { \LoadPresenterBackground { \l__pret_bg_tl } }
+\tl_if_eq:NnF \l__pret_fg_tl { default }
+  { \LoadPresenterForeground { \l__pret_fg_tl } }
 \RequirePackage { xpatch }
 \xpatchcmd { \maketitle } { \vskip 60\p@ } { } { } { }
 \xpretocmd { \part } {