% Copyright (c) 2026 Wang Yang (王阳) and contributors
% SPDX-License-Identifier: CC-BY-SA-4.0
\documentclass[11pt,a4paper,fontset=fandol]{ctexart}

\usepackage[a4paper,margin=22mm,headheight=15pt]{geometry}
\usepackage{array}
\usepackage{booktabs}
\usepackage{enumitem}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{longtable}
\usepackage{microtype}
\usepackage{needspace}
\usepackage{xcolor}

\setsansfont{Fira Sans}
\setmonofont{Fira Mono}

\definecolor{HUSTDocBlue}{HTML}{003B70}
\definecolor{HUSTDocAccent}{HTML}{C9A227}
\definecolor{HUSTDocInk}{HTML}{172230}
\definecolor{HUSTDocMuted}{HTML}{697586}
\definecolor{HUSTDocRule}{HTML}{D9DEE5}
\definecolor{HUSTDocPaper}{HTML}{F5F6F8}

\hypersetup{
  colorlinks=true,
  linkcolor=HUSTDocBlue,
  urlcolor=HUSTDocBlue,
  pdftitle={HUST Beamer Manual},
  pdfauthor={Wang Yang},
  pdfsubject={Unofficial HUST Beamer theme},
  pdfkeywords={HUST, Beamer, LaTeX, presentation theme}
}

\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\sffamily\small HUST Beamer}
\fancyhead[R]{\sffamily\small v0.7.1}
\fancyfoot[L]{\sffamily\footnotesize Unofficial community project}
\fancyfoot[R]{\sffamily\footnotesize\thepage}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0pt}

\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt}
\setlist[itemize]{leftmargin=5mm,itemsep=2pt,topsep=3pt}
\setlist[enumerate]{leftmargin=6mm,itemsep=2pt,topsep=3pt}

\lstdefinestyle{hustdoc}{
  basicstyle=\ttfamily\footnotesize,
  backgroundcolor=\color{HUSTDocPaper},
  rulecolor=\color{HUSTDocRule},
  frame=single,
  framesep=3mm,
  xleftmargin=0pt,
  columns=fullflexible,
  keepspaces=true,
  showstringspaces=false,
  breaklines=true,
  aboveskip=7pt,
  belowskip=7pt
}
\lstset{style=hustdoc}

\newcommand{\hustcommand}[1]{\texttt{\textbackslash #1}}
\newcommand{\hustfile}[1]{\texttt{#1}}
\newcommand{\hustnote}[1]{%
  \par\smallskip
  \begingroup
  \setlength{\fboxsep}{3mm}%
  \noindent
  \colorbox{HUSTDocPaper}{%
    \parbox{\dimexpr\linewidth-2\fboxsep\relax}{%
      \color{HUSTDocInk}\small #1}}%
  \endgroup
  \par\smallskip
}

\newif\ifhustdemofound
\IfFileExists{output/pdf/demo.pdf}{%
  \def\hustdemopdf{output/pdf/demo.pdf}%
  \hustdemofoundtrue
}{%
  \IfFileExists{example/demo.pdf}{%
    \def\hustdemopdf{example/demo.pdf}%
    \hustdemofoundtrue
  }{%
    \hustdemofoundfalse
  }%
}

\newcommand{\hustshowcase}[2]{%
  \begin{minipage}[t]{0.48\linewidth}
    \ifhustdemofound
      \setlength{\fboxsep}{0pt}%
      \fcolorbox{HUSTDocRule}{white}{%
        \includegraphics[page=#1,width=\dimexpr\linewidth-0.8pt\relax]%
          {\hustdemopdf}}%
    \else
      \fcolorbox{HUSTDocRule}{HUSTDocPaper}{%
        \parbox[c][45mm][c]{\dimexpr\linewidth-2\fboxsep\relax}{%
          \centering Demo PDF not found}}%
    \fi
    \par\vspace{2mm}
    {\sffamily\small\color{HUSTDocMuted}#2}
  \end{minipage}
}

\begin{document}

\hypersetup{pageanchor=false}
\begin{titlepage}
  \thispagestyle{empty}
  \noindent
  \begin{minipage}[c]{0.18\linewidth}
    \includegraphics[width=24mm]{assets/hust-emblem-color.pdf}
  \end{minipage}%
  \begin{minipage}[c]{0.82\linewidth}
    \raggedleft
    \includegraphics[width=70mm]{assets/hust-name-blue.pdf}
  \end{minipage}

  \vspace{18mm}
  {\color{HUSTDocAccent}\rule{18mm}{1.6pt}}\par
  \vspace{7mm}
  {\sffamily\bfseries\fontsize{31}{36}\selectfont
    \color{HUSTDocBlue}HUST Beamer\par}
  \vspace{4mm}
  {\sffamily\fontsize{16}{21}\selectfont
    \color{HUSTDocInk}Unofficial presentation theme manual\par}
  \vspace{8mm}
  {\large
    A compact 16:9 academic presentation system for\\
    Huazhong University of Science and Technology.\par}

  \vfill
  \begin{tabular}{@{}ll@{}}
    \sffamily\color{HUSTDocMuted}Version&
      \sffamily\bfseries 0.7.1\\[2mm]
    \sffamily\color{HUSTDocMuted}Maintainer&
      \sffamily\bfseries Wang Yang (王阳)\\[2mm]
    \sffamily\color{HUSTDocMuted}Engines&
      \sffamily\bfseries XeLaTeX and LuaLaTeX\\[2mm]
    \sffamily\color{HUSTDocMuted}Repository&
      \sffamily\href{https://github.com/fusang991/hust-beamer}%
        {github.com/fusang991/hust-beamer}
  \end{tabular}

  \vspace{15mm}
  {\small\color{HUSTDocMuted}
    This is an unofficial community project. HUST names and institutional
    identity marks remain subject to their respective rights and policies.}
\end{titlepage}

\hypersetup{pageanchor=true}
\pagenumbering{roman}
\tableofcontents
\clearpage
\pagenumbering{arabic}

\section{Overview}

HUST Beamer is an unofficial Beamer theme for Chinese-led academic talks,
thesis defenses, seminars, and research presentations. It provides a coherent
system for title pages, outlines, section dividers, ordinary frames, lists,
semantic boxes, and closing pages.

The visual hierarchy is intentionally restrained. Strong HUST identity is
concentrated on branded pages, while ordinary frames use neutral titles,
compact pagination, and an inset reading field. The theme builds on
\href{https://ctan.org/pkg/moloch}{Moloch}.

\begin{center}
  \hustshowcase{1}{Cover page with a concentrated identity field}
  \hfill
  \hustshowcase{9}{Ordinary frame with compact title geometry}
\end{center}

\subsection{Requirements}

\begin{itemize}
  \item XeLaTeX or LuaLaTeX;
  \item Beamer, Moloch, PGF/TikZ, \hustfile{etoolbox},
    \hustfile{graphicx}, and \hustfile{xcolor};
  \item \hustfile{ctex}, Fandol, and Fira for the bundled Chinese examples.
\end{itemize}

\hustnote{The page masters target a 16:9 canvas. pdfLaTeX and legacy 4:3
presentations are not supported configurations.}

\clearpage
\section{Quick start}

After the theme has been installed in a TeX search tree, a presentation loads
it with one line:

\begin{lstlisting}
\usetheme{hust}
\end{lstlisting}

A minimal Chinese presentation is:

\begin{lstlisting}
\documentclass[aspectratio=169,fontset=fandol]{ctexbeamer}
\usetheme{hust}

\setsansfont{Fira Sans}
\setCJKsansfont{FandolHei-Regular}[BoldFont=FandolHei-Bold]

\title{Research Talk}
\author{Your Name}
\institute{Huazhong University of Science and Technology}
\date{\today}

\hustsetdepartment{School or Department}
\hustsetevent{Academic Presentation}

\begin{document}
\maketitle

\section{Motivation}
\begin{frame}{First content frame}
  \begin{itemize}
    \item State the claim first.
    \item Add only the evidence needed to support it.
  \end{itemize}
\end{frame}
\end{document}
\end{lstlisting}

The complete compact source is available as
\hustfile{example/minimal.tex}; the longer demonstration is
\hustfile{example/demo.tex}.

\subsection{Installation}

When distributed through CTAN and TeX Live, install the package once:

\begin{lstlisting}
tlmgr install hust-beamer
\end{lstlisting}

For a manual user installation, place the five \hustfile{*.sty} files and the
complete \hustfile{assets/} directory under:

\begin{lstlisting}
TEXMFHOME/tex/latex/hust-beamer/
\end{lstlisting}

Use \hustfile{kpsewhich beamerthemehust.sty} to verify that TeX can discover
the installation. No project-local clone is needed after this one-time setup.

\section{Page families}

The theme treats the following as distinct page families:

\begin{enumerate}
  \item the cover establishes identity and metadata;
  \item the outline establishes reading order;
  \item section dividers reset pace and state one chapter claim;
  \item ordinary frames carry the argument with reduced branding;
  \item the closing page returns to the full identity field.
\end{enumerate}

\begin{center}
  \hustshowcase{2}{Structured outline}
  \hfill
  \hustshowcase{8}{Section divider}

  \vspace{6mm}
  \hustshowcase{13}{Data-dense result frame}
  \hfill
  \hustshowcase{15}{Closing page}
\end{center}

\subsection{Cover metadata}

The cover reads standard Beamer metadata together with optional Chinese and
English unit and event labels:

\begin{lstlisting}
\title{Presentation title}
\subtitle{Optional cover subtitle}
\author{Presenter}
\institute{Huazhong University of Science and Technology}
\date{\today}

\hustsetdepartment{School or Department}
\hustsetdepartmenten{English unit name}
\hustsetevent{Academic Presentation}
\hustseteventen{Research Talk}
\end{lstlisting}

The subtitle appears on the cover only. An optional portrait image can replace
the base of the blue cover field:

\begin{lstlisting}
\hustsetcoverimage[trim=0 8mm 0 8mm,clip]{figures/campus.jpg}
\hustclearcoverimage
\end{lstlisting}

\subsection{Section and closing pages}

Place a one-sentence section claim immediately before the corresponding
\hustcommand{section}. The note is consumed once:

\begin{lstlisting}
\hustsetsectionnote{One sentence that states the chapter claim.}
\section{Method}
\end{lstlisting}

Use the closing command inside a standout frame:

\begin{lstlisting}
\begin{frame}[standout]
  \hustclosing{Thank you}{Questions & Discussion}{Name - School}
\end{frame}
\end{lstlisting}

\subsection{Ordinary-frame geometry}

Ordinary titles begin at a 12 mm physical margin. The body begins at 17 mm,
creating a deliberate 5 mm step between page-level metadata and the reading
field. Frame subtitles are intentionally not rendered on ordinary frames, and
no decorative rule appears beneath the title.

\hustnote{Do not cancel the built-in title/body step with negative spacing.
Treat it as part of the page master rather than per-frame whitespace.}

\clearpage
\section{Lists and semantic boxes}

Native Beamer environments receive the theme styling automatically.
\hustfile{itemize} is used for parallel claims; \hustfile{enumerate} is
reserved for a real sequence.

\begin{lstlisting}
\begin{itemize}
  \hustitem{Claim first}{One supporting line follows.}
  \hustitem{Keep levels scarce}{Nest only for conditions or exceptions.}
\end{itemize}
\end{lstlisting}

The two recurring content-box families are also native Beamer blocks:

\begin{lstlisting}
\begin{block}{Primary conclusion}
  Explanation, comparison, summary, or future work.
\end{block}

\begin{exampleblock}{Definition or local emphasis}
  A model, formula, evidence region, or secondary point.
\end{exampleblock}

\begin{alertblock}{Risk or failure}
  A genuine warning, limitation, or failure state.
\end{alertblock}
\end{lstlisting}

\begin{center}
  \hustshowcase{6}{Itemize and enumerate hierarchy}
  \hfill
  \hustshowcase{7}{Blue and pink semantic box families}
\end{center}

Blue identifies a primary semantic region. Pink identifies a definition,
formula, or secondary region. Red is reserved for actual warnings and failure
states. A slide normally needs no more than one primary box or two compact,
related boxes.

\section{Public interface}

\renewcommand{\arraystretch}{1.18}
\begin{longtable}{@{}>{\raggedright\arraybackslash}p{86mm}
                    >{\raggedright\arraybackslash}p{59mm}@{}}
  \toprule
  \sffamily\bfseries Command & \sffamily\bfseries Purpose\\
  \midrule
  \endfirsthead
  \toprule
  \sffamily\bfseries Command & \sffamily\bfseries Purpose\\
  \midrule
  \endhead
  \hustcommand{hustsetdepartment}\hustfile{\{...\}}&
    Chinese unit name on the cover.\\
  \hustcommand{hustsetdepartmenten}\hustfile{\{...\}}&
    English unit name on the cover.\\
  \hustcommand{hustsetdepartmentshort}\hustfile{\{...\}}&
    Legacy compatibility alias; it is not rendered in ordinary footers.\\
  \hustcommand{hustsetevent}\hustfile{\{...\}}&
    Chinese presentation type above the cover title.\\
  \hustcommand{hustseteventen}\hustfile{\{...\}}&
    English presentation type above the cover title.\\
  \hustcommand{hustsetsectionnote}\hustfile{\{...\}}&
    One-shot claim shown on the next section divider.\\
  \hustcommand{hustsetcoverimage}\hustfile{[...]\{...\}}&
    Optional photograph behind the blue cover identity field.\\
  \hustcommand{hustclearcoverimage}&
    Restore the solid-blue cover identity field.\\
  \hustcommand{hustsetassetpath}\hustfile{\{...\}}&
    Override the directory containing the vector identity assets.\\
  \hustcommand{hustsetlogo}\hustfile{\{...\}}&
    Override the automatically discovered emblem; ensure that the custom
    mark remains legible on dark pages.\\
  \hustcommand{hustbrandmark}\hustfile{[height]}&
    Render the active color emblem.\\
  \hustcommand{hustbrandmarkinverse}\hustfile{[height]}&
    Render the inverse emblem.\\
  \hustcommand{hustwordmark}\hustfile{[width]}&
    Render the blue Chinese standard name.\\
  \hustcommand{hustwordmarkinverse}\hustfile{[width]}&
    Render the inverse Chinese standard name.\\
  \hustcommand{hustkicker}\hustfile{\{...\}}&
    Render a compact neutral editorial label.\\
  \hustcommand{hustitem}\hustfile{\{title\}\{note\}}&
    Render a two-level item inside a native list.\\
  \hustcommand{hustmetric}\hustfile{\{value\}\{label\}}&
    Render an open metric with supporting evidence.\\
  \hustfile{hustoutlinepage}&
    Structured outline environment for use in a plain top-aligned frame.\\
  \hustcommand{hustoutlineitem}\hustfile{\{n\}\{title\}\{note\}}&
    Numbered outline or conclusion row.\\
  \hustcommand{hustclosing}\hustfile{\{title\}\{subtitle\}\{detail\}}&
    Closing content for a standout frame.\\
  \bottomrule
\end{longtable}

\section{Brand assets}

The package contains four static vector PDF assets:

\begin{itemize}
  \item \hustfile{hust-emblem-color.pdf};
  \item \hustfile{hust-emblem-white.pdf};
  \item \hustfile{hust-name-blue.pdf};
  \item \hustfile{hust-name-white.pdf}.
\end{itemize}

They are discovered automatically from the bundled \hustfile{assets/}
directory. If an installation rearranges that directory, set
\hustcommand{hustsetassetpath}\hustfile{\{path/to/assets\}} in the preamble.

These files were generated with
\href{https://ctan.org/pkg/hustvisual}{hustvisual v1.0.0}. The theme does not
load \hustfile{hustvisual} at runtime.

\hustnote{This package is unofficial and does not imply endorsement by HUST.
The theme code and original documentation use CC BY-SA 4.0. HUST names,
emblems, wordmarks, and other institutional identity elements are excluded
from that grant and remain subject to the applicable institutional policies.}

\section{Build, support, and maintenance}

Build the demonstration from the repository root:

\begin{lstlisting}
latexmk -xelatex example/demo.tex
latexmk -lualatex example/demo.tex
\end{lstlisting}

The release is tested with both engines. Report reproducible problems at:

\begin{center}
  \url{https://github.com/fusang991/hust-beamer/issues}
\end{center}

Include the engine, TeX Live version, a minimal source file, and the relevant
log excerpt. The maintained design contract is documented in
\hustfile{DESIGN.md}.

\subsection{Troubleshooting}

\begin{longtable}{@{}>{\raggedright\arraybackslash}p{52mm}
                    >{\raggedright\arraybackslash}p{93mm}@{}}
  \toprule
  \sffamily\bfseries Symptom & \sffamily\bfseries Check\\
  \midrule
  \hustfile{beamerthememoloch.sty} not found&
    Install the \hustfile{moloch} package with the package manager supplied
    by the TeX distribution.\\
  Brand mark is missing&
    Keep the complete \hustfile{assets/} directory beside the theme files, or
    set \hustcommand{hustsetassetpath}.\\
  Fira font warning&
    Install the \hustfile{fira} package, or choose locally available sans and
    mono fonts in the document preamble.\\
  Chinese text is blank or incorrect&
    Compile the bundled examples with XeLaTeX or LuaLaTeX and retain the
    \hustfile{ctexbeamer} class.\\
  Theme is not discovered&
    Run \hustfile{kpsewhich beamerthemehust.sty}; refresh the filename
    database when required by the local TeX distribution.\\
  \bottomrule
\end{longtable}

\vspace{8mm}
\begin{center}
  \includegraphics[height=18mm]{assets/hust-emblem-color.pdf}
  \hspace{8mm}
  \includegraphics[width=58mm]{assets/hust-name-blue.pdf}
\end{center}

\subsection{License and maintainer}

\begin{tabular}{@{}>{\color{HUSTDocMuted}}p{34mm}
                    >{\raggedright\arraybackslash}p{105mm}@{}}
  Maintainer & Wang Yang (王阳)\\
  Theme code & CC BY-SA 4.0\\
  Brand assets & Separate institutional rights notice; see
    \hustfile{LICENSE} and \hustfile{NOTICE.md}\\
  Repository & \url{https://github.com/fusang991/hust-beamer}
\end{tabular}

\vspace{8mm}
{\small\color{HUSTDocMuted}
Documentation version 0.7.1, dated 2026-07-20.}

\end{document}