docs: customization

.github/workflows/build.yml

@@ -67,6 +67,7 @@ jobs:
           run: |
             export diffexe="diff -U 3"
             apk add zip diffutils
+            tlmgr update l3build
             .github/ci/build_package.sh
         name: build package with l3build
       - name: check if generated files are of latest version

src/build.lua

@@ -21,7 +21,7 @@ typesetfiles     = {"sjtubeamerdevguide.tex","sjtubeamer.tex"}
 -- typesetfiles     = {"sjtubeamer.tex"}
 -- typesetruns      = 1 -- for debug. Some reference may not be linked.
 -- typesetdemofiles = {"min.tex"}
--- cachedemo        = true -- cache the demo
+
 typesetsuppfiles = {"head.png","plant.jpg","test.csv","testgraph.tex","ref.bib","sjtug.pdf","sjtug_text.pdf","tutorial/"}
 
 -- Regression tests mainly test the decoupling properties between kernel modules.
@@ -61,8 +61,14 @@ function update_tag(file,content,tagname,tagdate)
     return content
 end
 
+-- Compiling file in a certain receipe: tex -> biber(-) -> tex(+)
+-- by assigning different symbols in the filename.
+-- This will patch l3build compilation "tex" command.
 function compile_file(dir, cmd, filename, native)
     local errorlevel = 0
+    if os.type == "windows" then
+        native = false
+    end
     if native then
         errorlevel = tex(filename, dir, cmd)
     else
@@ -83,10 +89,13 @@ function compile_file(dir, cmd, filename, native)
     return errorlevel
 end
 
--- Generate tutorial files before compiling the doc.
+
 -- NOTICE: if you want to save the tourial step pdf,
---         please enter support/tutorial and run cache_pdf.sh
---         if you want to clean the cache, please run clean_pdf.sh 
+--         please uncomment the following line.
+
+-- cachedemo        = true -- cache the demo
+
+-- Generate tutorial files before compiling the doc.
 function typeset_demo_tasks()
     local errorlevel = 0
     local tutorialdir = typesetdir .. "/tutorial"
@@ -96,7 +105,7 @@ function typeset_demo_tasks()
     print("Please modify the cachedemo variable in build.lua file.")
     print("============================================================")
 
-    print("Compiling precomiled header...")
+    print("Compiling precompiled header...")
     local cacheable = true
     local headerfilename = "commonheader"
     local etypesetcommand = etypesetexe .. "  -ini -interaction=nonstopmode -jobname=" .. headerfilename .. " \"&" .. typesetexe .. "\" mylatexformat.ltx "

src/doc/sjtubeamer.tex

@@ -465,12 +465,36 @@ \chapter{背景}
 \beamerdemo[1]{step20.tex}
 
 \begin{commentlist}
-  \item \texttt{\textbackslash{}setbeamertemplate} 可以设定背景图。
+  \item \texttt{\textbackslash{}setbeamertemplate\{background\}\{\}} 可以设定背景图。如果设定为空，将会清除现在已经设定的背景图。请在主题加载完成后设定。
   \item \texttt{\textbackslash{}stamparray} 可以用于生成印记矩阵。$^*$
   \item \texttt{\textbackslash{}bgcenterbox} 命令可以用于居中背景图。$^*$
   \item 作为文字的背景，其透明度应该较低或者颜色偏淡。
 \end{commentlist}
 
+\chapter{自定}
+
+上面的自定义配置可以全部写入一个样式文件中，以在加载主题后加载这个自定义样式文件。采用 \texttt{my} 选项可以从零开始打造这些配置。
+
+\beamerdemo[1]{step21.tex}
+
+\tcbinputlisting{listing file={tutorial/my.sty},
+  listing only,
+  enhanced jigsaw,
+  lower separated=false,
+  leftlower=0pt,rightlower=0pt,middle=0pt,
+  listing options={
+      style=tcblatex,
+      texcsstyle=*\color{red!70!black}
+    },
+  tile,
+  title={\faEdit 样式 my.sty}}
+
+\begin{commentlist}
+  \item 使用 \texttt{\textbackslash{}definecolor} 定义 \texttt{cprimary}、\texttt{csecondary}$^*$ 可以改变主题颜色。
+  \item 使用 \texttt{\textbackslash{}defbeamertemplatealias} 可以通过已有模板进行赋值，这里可以用于设置标题页与尾页的样式为现有样式。
+  \item 更多设置请参见\href{run:sjtubeamerdevguide.pdf}{开发文档}第3.3节。
+\end{commentlist}
+
 %TODO: 未来的开发计划
 %\chapter{字体}
 

src/doc/sjtubeamerdevguide.tex

@@ -211,7 +211,7 @@ \subsubsection{Kernel Function Definition}
 
 \subparagraph{Pros:} Using this method could get an optional parameter.
 
-\subparagraph{Cons:} This method is less readable. And have to decide to use \verb"\newcommand" (check on duplicate functions) or \verb"\providecommand" (skip uniquness check).
+\subparagraph{Cons:} This method is less readable. And have to decide to use \verb"\newcommand" (check on duplicate functions) or \verb"\providecommand" (no effect if defined).
 
 \subparagraph{Decision:} Just use this method if you want an optional parameter. You should not write a function with more than one optional parameters.
 
@@ -430,14 +430,14 @@ \subsection{Communication Model}
 
 \begin{table}[h]
   \begin{tabular}{l|>{\ttfamily}l|>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}
-            & parent                             & color                           & inner                           & outer                                    \\
+            & parent                             & color                           & inner                           & outer                             \\
     \hline
-    cover   & \textbackslash{}sjtubeamer@cover   &                                 & \textbackslash{}...@inner@cover &                                          \\
-    color   & \textbackslash{}sjtubeamer@color   & \textbackslash{}...@color@color & \textbackslash{}...@inner@color &                                          \\
-    lum     & \textbackslash{}sjtubeamer@lum     & \textbackslash{}...@clolor@lum  &                                 &                                          \\
-    lang    & \textbackslash{}sjtubeamer@lang    &                                 & \textbackslash{}...@inner@lang  &                                          \\
-    nav     & \textbackslash{}sjtubeamer@nav     &                                 &                                 & \textbackslash{}...@outer@nav            \\
-    logopos & \textbackslash{}sjtubeamer@logopos &                                 &                                 & \textbackslash{}sjtubeamer@outer@logopos \\
+    cover   & \textbackslash{}sjtubeamer@cover   &                                 & \textbackslash{}...@inner@cover &                                   \\
+    color   & \textbackslash{}sjtubeamer@color   & \textbackslash{}...@color@color & \textbackslash{}...@inner@color &                                   \\
+    lum     & \textbackslash{}sjtubeamer@lum     & \textbackslash{}...@clolor@lum  &                                 &                                   \\
+    lang    & \textbackslash{}sjtubeamer@lang    &                                 & \textbackslash{}...@inner@lang  &                                   \\
+    nav     & \textbackslash{}sjtubeamer@nav     &                                 &                                 & \textbackslash{}...@outer@nav     \\
+    logopos & \textbackslash{}sjtubeamer@logopos &                                 &                                 & \textbackslash{}...@outer@logopos \\
   \end{tabular}
   \vskip 3pt\moveright 0in\vbox{\hrule width3cm \vskip 3pt
     \moveleft 0em \vbox{
@@ -469,6 +469,16 @@ \subsection{Template Management}
 
 Since large source code may cause a performance drop on compiling. We have figure out a precompiling mechanism to reduce the templates it generates. See Section \ref{sec:precompile}.
 
+You could also make your customized style by using \texttt{my} option to setup all components from scratch without leaving the \themename\ ecosystem with all those utilities.
+
+Developers mainly have two ways to add your template. One is to modify the source code directly where the placeholder for \texttt{my} style has been left blank already. The other is to use a new style file \texttt{my.sty} (whatever the filename) and load it after loading the theme in order to override the previous settings made by \themename\ itself. And you could use \texttt{\textbackslash{}defbeamertemplatealias} to assign \texttt{my} by other current template. Remember, the placeholder is all left blank, and if you encountered
+\begin{verbatim}
+  Divided by zero
+\end{verbatim}
+errors, you have to assign the placeholder for a correct resizing. And if you really want to left it blank, use \texttt{\textbackslash{}hphantom\{-\}} or \texttt{\textbackslash{}vphantom\{-\}} to create a void box.
+
+You could refer to the user guide for a sample file. And the loading on the package is not that necessary as long as you load the theme before it is loaded, which is only for the sake of completeness.
+
 \subsection{Logo Color System}
 
 \themename\ has its own color model on logo. The main macro is \verb"\definelogo", which will generate a macro on its file name.
@@ -477,7 +487,7 @@ \subsection{Logo Color System}
 
 However, this only creates a square mask. We have to crop it for some rectangular bounding boxes. Our macro will decide from your input on horizontal and vertical cropping size for your picture fill the height or fill the width. And crop the area symmetrically.
 
-\begin{figure}
+\begin{figure}[h]
   \begin{tikzpicture}
     \draw [fill=black] (-4,1) rectangle (-2,-1);
 
@@ -561,9 +571,11 @@ \subsection{Old \TeX\ Distribution}
 
 For compatibility issues, you need to define the \verb"\sjtubeamer@compatible" variable to \verb"false" to close the related rendering before the theme is loaded.
 
+\begin{verbatim}
 \makeatletter
 \def\sjtubeamer@compatible{false}
 \makeatother
+\end{verbatim}
 
 \begin{tabular}{c|cccccccc}
   \TeX\ Live & 2021    & 2020    & 2019    & 2018    & 2017    & 2016    & 2015    & 2014 \\
@@ -587,12 +599,12 @@ \subsection{Pre-Compilation}
 
 In practice, we find that the \texttt{path fading} in Ti\emph{k}Z is not compatible with the caching mechanism, and it introduces more issues in PDF compatibility. Before it is solved in a future version of Ti\emph{k}Z, the background pattern will be skipped in the title page template in \texttt{min} theme by adding \verb"\sjtubeamer@compatible" to \verb"false".
 
-If your unit test doesn't want to be cached, you could add a blank square brackets.
+If your unit test doesn't want to be cached, you could add blank square brackets.
 \begin{verbatim}
   \documentclass[]{ctexbeamer}
 \end{verbatim}
 
-More details about this experimental caching mechanism in \texttt{l3build doc}, see \texttt{build.lua}. And you could change the default behavior of caching the demo files by changing \texttt{cahcedemo} to \texttt{true}.
+More details about this experimental caching mechanism in \texttt{l3build doc}, see \texttt{build.lua}. And you could change the default behavior of caching the demo files by changing \texttt{cachedemo} to \texttt{true}.
 
 \section{Developer}
 \begin{itemize}

src/source/beamercolorthemesjtubeamer.dtx

@@ -16,7 +16,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamercolorthemesjtubeamer}[2021/11/25 sjtubeamer color theme v2.4.0]
+\ProvidesPackage{beamercolorthemesjtubeamer}[2021/12/01 sjtubeamer color theme v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}

src/source/beamerfontthemesjtubeamer.dtx

@@ -16,7 +16,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerfontthemesjtubeamer}[2021/11/25 sjtubeamer font theme v2.4.0]
+\ProvidesPackage{beamerfontthemesjtubeamer}[2021/12/01 sjtubeamer font theme v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}

src/source/beamerinnerthemesjtubeamer.dtx

@@ -16,7 +16,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerinnerthemesjtubeamer}[2021/11/25 sjtubeamer inner theme v2.4.0]
+\ProvidesPackage{beamerinnerthemesjtubeamer}[2021/12/01 sjtubeamer inner theme v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}
@@ -160,11 +160,11 @@
 %  \end{macro}
 %
 %  \begin{macro}{\bgcenterbox}
-%   Define a command for USERS to make a centered background box easily. Move the defination on \verb"\sjtubeamer@logocolor" to the inner environment, to avoid the shift on centering. And since the definition has already been moved into the inner group, the definition here is \emph{locale} and no more stack saving is needed.
+%   Define a command for USERS to make a centered background box easily. 
+%   The change on color is now deprecated.
 %    \begin{macrocode}
 \newcommand{\bgcenterbox}[1]{
   \parbox[c][1.1\paperheight][c]{\paperwidth}{
-    \def\sjtubeamer@logocolor{cprimary!50}
     \centering\resizebox{\paperwidth}{!}{#1}
   }
 }
@@ -177,6 +177,7 @@
 % NOTICE: if you are using your own title graphic, please use png image with predefined color and transparency. Since it is beyond the control of logo color system. Or you could use the provided command in the sjtuvi library to create your own masked picture in order to follow the logo color system (The provided picture should be white and transparent in the background).
 %
 %    max theme has the background.
+%    \verb"\setbeamertemplate{background}{}" after loading the theme will disable it.
 %    \begin{macrocode}
 %<*maxplus>
 \if\EqualOption{inner}{cover}{maxplus}

src/source/beamerouterthemesjtubeamer.dtx

@@ -16,7 +16,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerouterthemesjtubeamer}[2021/11/25 sjtubeamer outer theme v2.4.0]
+\ProvidesPackage{beamerouterthemesjtubeamer}[2021/12/01 sjtubeamer outer theme v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}

src/source/beamerthemesjtubeamer.dtx

@@ -37,7 +37,7 @@
 % ------------------------------------------------------------------- \fi
 % \iffalse
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{beamerthemesjtubeamer}[2021/11/25 sjtubeamer parent theme v2.4.0]
+\ProvidesPackage{beamerthemesjtubeamer}[2021/12/01 sjtubeamer parent theme v2.4.1]
 % \fi
 %
 % \subsection{Parent Theme}

src/source/sjtucover.dtx

@@ -13,7 +13,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{sjtucover}[2021/11/25 cover library for sjtubeamer v2.4.0]
+\ProvidesPackage{sjtucover}[2021/12/01 cover library for sjtubeamer v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}
@@ -432,7 +432,14 @@
     \usebeamercolor[fg]{palette primary}
     \usebeamerfont{title}\noindent#1
     \vskip1em%
-    \usebeamerfont{subtitle}\insertauthor~$\cdot$~\inserttitle
+    \usebeamerfont{subtitle}
+    \insertauthor
+    \ifx\insertauthor\@empty
+    \else
+      \ifx\inserttitle\@empty
+      \else~$\cdot$~\fi
+    \fi
+    \inserttitle
   \end{beamercolorbox}%
   \vfill
   \vskip3.5em

src/source/sjtuvi.dtx

@@ -13,7 +13,7 @@
 % \iffalse
 %<*package>
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{sjtuvi}[2021/11/25 Visual Identity System library for sjtubeamer v2.4.0]
+\ProvidesPackage{sjtuvi}[2021/12/01 Visual Identity System library for sjtubeamer v2.4.1]
 %</package>
 % \fi
 % \CheckSum{0}

src/support/tutorial/my.sty

@@ -0,0 +1,13 @@
+\usepackage{sjtuvi}
+\usepackage{sjtucover}
+\logo{\resizebox{1cm}{!}{\includegraphics{vi/sjtug.pdf}}}
+\titlegraphic{\includegraphics{sjtuphoto}}
+\definecolor{cprimary}{RGB}{225,111,11}
+\definelogo{sjtugtext}{0}{0}
+\setbeamertemplate{background}{
+    \bgcenterbox{
+        \sjtugtext[opacity=0.15]
+    }
+}
+\defbeamertemplatealias{title page}{my}{maxplus}
+\defbeamertemplatealias{bottom page}{my}{min}