feat: base and base-options class options

`article` and `report` class options are deprecated.

testfiles/secblock.lvt

@@ -1,6 +1,6 @@
 \input{regression-test}
 \AtBeginDocument{\START}
-\documentclass[report]{presenter}
+\documentclass[base=report]{presenter}
 \LoadPresenterBackground{secblock}
 \begin{document}
 

texmf/doc/latex/presenter/presenter-code.tex

@@ -1,5 +1,5 @@
 %% ------------------------------------------------------------------------
-%% Copyright (C) 2023 Log Creative <[email protected]>
+%% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %%
 %% This work may be distributed and/or modified under the
 %% conditions of the LaTeX Project Public License, either version 1.3
@@ -22,7 +22,7 @@
 \NewDocumentCommand{\presenter}{}{\textsc{Presenter}}
 \title{\presenter: A \LaTeX{} presentation framework with seamless migration}
 \author{Zilong Li (Log Creative)}
-\date{2023-10-23 \quad v0.7.0}
+\date{2024-01-14 \quad v0.7.1}
 
 \usepackage{array}
 \usepackage{float}
@@ -83,7 +83,7 @@
 
 \vfil
 
-Copyright \copyright{} 2023 Log Creative
+Copyright \copyright{} 2023--2024 Log Creative
 (\href{mailto:[email protected]}{\texttt{[email protected]}})
 
 This work may be distributed and/or modified under the
@@ -240,16 +240,22 @@ \section{Basics}
 
 \section{Options}
 
-\begin{function}[added=2023-02-04]{article, report}
-  However, if you want to use \tn{chapter} level, pass the \verb"report"
-  option to the document class \cls{presenter} like
-  \verb"\documentclass[report]{presenter}". The default is \verb"article"
-  based.
+\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}
-    It sounds not okay to use \cls{book} class as the base document class, since
-    they are typically pretty long. But if you want to use it as the base class,
-    or any other document class, use the package \pkg{presenter} instead.
+\begin{texnote}
+  If you want to customize the loading of the \presenter{} code,
+  you could use the package \pkg{presenter} instead.
 
 \begin{center}
 \begin{minipage}[c]{0.45\textwidth}
@@ -266,8 +272,7 @@ \section{Options}
   \previewtest{package}
 \end{minipage}
 \end{center}
-  \end{texnote}
-\end{function}
+\end{texnote}
 
 \section{Templates}
 
@@ -418,6 +423,13 @@ \subsection{Edit Templates}
 The \LaTeX{} Project.
 \newblock The \pkg{xtemplate} package: Prototype document functions, 2023.
 \newblock \url{https://www.ctan.org/pkg/xtemplate}.
+
+\bibitem{tlc3}
+Frank Mittelbach and Ulrike Fischer.
+\newblock The \LaTeX{} Companion,
+\newblock 3rd Edition,
+\newblock Addison-Wesly, 2023.
+
 \end{thebibliography}
 
 \PrintChanges

texmf/doc/latex/presenter/presenter-doc.tex

@@ -1,5 +1,5 @@
 %% ------------------------------------------------------------------------
-%% Copyright (C) 2023 Log Creative <[email protected]>
+%% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %%
 %% This work may be distributed and/or modified under the
 %% conditions of the LaTeX Project Public License, either version 1.3

texmf/source/latex/presenter/presenter.dtx

@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ------------------------------------------------------------------------
-% Copyright (C) 2023 Log Creative <[email protected]>
+% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -19,12 +19,15 @@
 % \begin{implementation}
 %
 % \iffalse
+% The setting of key-based options through CamelCase commands (
+% \cs{DeclareKeys}, \cs{DeclareUnknownKeyHandler}, \cs{ProcessKeysOptions}
+% ) is only available after the June 2022 release \cite{tlc3}.
 %<*class|package>
-\NeedsTeXFormat{LaTeX2e}[2020/10/01]
+\NeedsTeXFormat{LaTeX2e}[2022/06/01]
 %<class>\ProvidesExplClass
 %<package>\ProvidesExplPackage
   {presenter}
-  {2023-10-23}{0.7.0}
+  {2024-01-14}{0.7.1}
 %<class>  {A LaTeX presentation framework with seamless migration (class)}
 %<package>  {A LaTeX presentation framework with seamless migration (package)}
 %</class|package>
@@ -42,33 +45,93 @@
 %<@@=pretcls>
 %    \end{macrocode}
 %
-% \begin{variable}[int]{\g_@@_article_bool}
-% Base class boolean variable if it is \cls{article} base class.
+% \begin{variable}{\l__pretcls_base_tl, \l__pretcls_base_options_clist}
+% Store the base class and its options.
 %    \begin{macrocode}
-\bool_new:N \g_@@_article_bool
-\bool_gset_true:N \g_@@_article_bool
+\tl_new:N \l__pretcls_base_tl
+\clist_new:N \l__pretcls_base_options_clist
 %    \end{macrocode}
+% The base options are stored in comma list (\verb"clist")
+% instead of token list (\verb"tl") type
+% to avoid the unwanted space token in the options.
 % \end{variable}
 %
-% Declare option \verb"report" and \verb"article" for selecting respective base
-% classes.
+% 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.
 %    \begin{macrocode}
-\DeclareOption { article } { \bool_gset_true:N  \g_@@_article_bool }
-\DeclareOption { report  } { \bool_gset_false:N \g_@@_article_bool }
+\DeclareKeys [ pretcls ] {
+%    \end{macrocode}
+% \begin{texnote}
+%   Instead of using \cs{SetKeys}, \presenter{} uses \verb".initial" property on
+%   those keys. Be aware that the \verb".initial" property should be always
+%   declared after \verb".store" or \verb".<type>_set:N" property to avoid
+%   uninitialized variables!
+% \end{texnote}
+%
+% \begin{macro}{base}
+% The base class to be loaded before the package \pkg{presenter}.
+%    \begin{macrocode}
+  base.tl_gset:N = \l__pretcls_base_tl,
+  base.initial:n = article,
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{base-options}
+% The option comma list to be passed to the base class.
+%    \begin{macrocode}
+  base-options.clist_gset:N = \l__pretcls_base_options_clist,
+  base-options.initial:n = ,
+%    \end{macrocode}
+% \end{macro}
+%
+%    \begin{macrocode}
+}
 %    \end{macrocode}
 %
-% Pass other options to both the potential document classes.
+% User could use the traditional ``global'' options to pass options to the
+% setted \verb"base" class.
+% The usage should be replaced by the \verb"base-options" key above
+% and only acts as a compatibility feature with other \LaTeX{} classes.
+% Unlike \verb"base-options" key, those ``global'' options are only available
+% after the \verb"base" key is set in the key-value list of this class.
+% 
+% \begin{texnote}
+% The reason is as follows. 
+% Since the order of keys processed by \cs{ProcessKeyOptions} is in the order of
+% the key-value list,
+% if those ``global'' options are set before the \verb"base" key, 
+% those options will be passed to the initial value of \verb"base" key,
+% i.e., \cls{article} class.
+% As a result, those ``pre-base'' options will be ignored if \verb"base" is
+% not \verb"article".
+% \end{texnote}
 %    \begin{macrocode}
-\DeclareOption* {
-  \PassOptionsToClass { \CurrentOption } { article }
-  \PassOptionsToClass { \CurrentOption } { report  }
+\DeclareUnknownKeyHandler [ pretcls ] {
+  \PassOptionsToClass { \CurrentOption } { \l__pretcls_base_tl }
 }
 %    \end{macrocode}
 %
-% Process the options and load the selected base class. Load the main package.
+% Process the class options.
+%    \begin{macrocode}
+\ProcessKeyOptions [ pretcls ]
+%    \end{macrocode}
+%
+% Pass options in \verb"base-options" to the base class.
+% Then load the base class.
+%    \begin{macrocode}
+\PassOptionsToClass { \l__pretcls_base_options_clist } { \l__pretcls_base_tl }
+\LoadClass { \l__pretcls_base_tl }
+%    \end{macrocode}
+%
+% \begin{texnote}
+% The decision to make use of \cs{DeclareUnknownKeyHandler} with trade-off
+% instead of \cs{LoadClassWithOptions} is for avoiding the warnings of unused
+% options raised by the latter one.
+% \end{texnote}
+%
+% Load \cls{presenter} main package.
 %    \begin{macrocode}
-\ProcessOptions*
-\LoadClass { \bool_if:NTF \g_@@_article_bool { article } { report } }
 \RequirePackage { presenter }
 %    \end{macrocode}
 %

texmf/source/latex/presenter/presenter.ins

@@ -1,5 +1,5 @@
 %% ------------------------------------------------------------------------
-%% Copyright (C) 2023 Log Creative <[email protected]>
+%% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %%
 %% This work may be distributed and/or modified under the
 %% conditions of the LaTeX Project Public License, either version 1.3
@@ -21,7 +21,7 @@
 
 \preamble
 ------------------------------------------------------------------------
-Copyright (C) 2023 Log Creative <[email protected]>
+Copyright (C) 2023--2024 Log Creative <[email protected]>
 
 This work may be distributed and/or modified under the
 conditions of the LaTeX Project Public License, either version 1.3

texmf/source/latex/presenter/pretbg.dtx

@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ------------------------------------------------------------------------
-% Copyright (C) 2023 Log Creative <[email protected]>
+% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -26,7 +26,7 @@
 %<secblock>  {pretbg-secblock}
 %<progressbar>  {pretbg-progressbar}
 %<img>  {pretbg-img}
-  {2023-10-23}{0.7.0}
+  {2024-01-14}{0.7.1}
 %<default>  {default background style for presenter}
 %<block>  {block background style for presenter}
 %<iiiblock>  {iiiblock background style for presenter implemented in l3draw}

texmf/source/latex/presenter/pretfg.dtx

@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ------------------------------------------------------------------------
-% Copyright (C) 2023 Log Creative <[email protected]>
+% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -24,7 +24,7 @@
 %<dual>  {pretfg-dual}
 %<cascade>  {pretfg-cascade}
 %<img>  {pretfg-img}
-  {2023-10-23}{0.7.0}
+  {2024-01-14}{0.7.1}
 %<default>  {default foreground style for presenter}
 %<dual>  {dual foreground style for presenter}
 %<cascade>  {cascade foreground style for presenter}

texmf/source/latex/presenter/pretsec.dtx

@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ------------------------------------------------------------------------
-% Copyright (C) 2023 Log Creative <[email protected]>
+% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -21,7 +21,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}[2020/10/01]
-\ProvidesExplPackage{pretsec}{2023-10-23}{0.7.0}
+\ProvidesExplPackage{pretsec}{2024-01-14}{0.7.1}
   {sectioning support pack for presenter}
 %</package>
 % \fi

texmf/source/latex/presenter/prettpl.dtx

@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ------------------------------------------------------------------------
-% Copyright (C) 2023 Log Creative <[email protected]>
+% Copyright (C) 2023--2024 Log Creative <[email protected]>
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -21,7 +21,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}[2020/10/01]
-\ProvidesExplPackage{prettpl}{2023-10-23}{0.7.0}
+\ProvidesExplPackage{prettpl}{2024-01-14}{0.7.1}
   {template management for presenter}
 %</package>
 % \fi