repository·master·Indexed 20 days ago
https://github.com/nju-lug/njuthesisA LaTeX document class designed to meet the formatting requirements of Nanjing University for undergraduate, graduate, and postdoctoral theses. It includes support for blind review mode, biblatex integration via gb7714-2015, and is available through the NJU TeX online platform or local compilation using XeLaTeX.
The njuthesis document class is designed for creating Nanjing University undergraduate theses, graduate theses, and postdoctoral reports. It follows the official formatting standards provided by the undergraduate and graduate schools.
For a detailed guide on features and usage, refer to the User Manual.
When working with l3keys for configuration:
l3keys to disable user-level key paths, ensure that internal \keys_set:nn forwarding points remain functional and are not accidentally blocked.l3keys grouping mechanism (e.g., \keys_set_exclude_groups:nnn) instead of checking and filtering keys one by one. This improves maintainability.The jusetup command uses a normalization model for its optional arguments. When you call jusetup[module]{key=value}, the command normalizes this into a top-level assignment where the module name and the full nested key-value path are passed to the nju namespace.
For example, jusetup[info]{title=My Thesis} is internally treated as ju_keys_set:nn { nju } { info = { title = My Thesis } }. This ensures that filtering mechanisms (such as blind review filters) applied to the nju namespace correctly propagate to nested modules like info.
In njuthesis, the cover and declaration page hooks are registered during the loading of the thesis type .def files (e.g., njuthesis-undergraduate.def).
Crucial Rule: Any class option that affects whether a hook is registered (such as decl-page) must be normalized before the .def file is loaded. Once a hook is registered via the .def file, changing the boolean flag that controls its registration will not unregister the code already added to the hook.
nju / option.\ProcessKeysOptions { nju / option }.decl-page = false if anonymous review mode is active)..def file. (This is when hooks are actually registered based on the final state of the options).config class options.The logo color mechanism (introduced in v1.5.0) uses bundled PDF assets instead of procedural drawing.
\c_@@_logo_color_tl (either black or purple) in its .def file. This constant is used to initialize the nju-logo-color key.nju-logo-color, a choice handler updates internal properties (\l_@@_logo_file_prop) with the corresponding filename.cover/begin hook (just before the cover is rendered), these properties are copied to token list (tl) variables. The actual rendering is performed via \includegraphics using the selected PDF.Internal commands use specific dimension variables based on the context (suffix):
\l_@@_emblemwd_dim / \l_@@_namewd_dim) for standard covers.i: Uses \l_@@_emblemwdi_dim for the emblem on the Undergraduate Integrity Statement page.ii: Uses \l_@@_emblemwdii_dim for the emblem on Graduate English covers.When modifying how users configure the class via \njusetup, use source/njuthesis.dtx as the source of truth.
Key implementation rules:
nju should be routed through internal filtering setters rather than using raw l3keys meta-expansion.clist after option processing. If the clist is empty, alias \@@_keys_set:nn to \keys_set:nn, or define it to call \keys_set_exclude_groups:nnn when a filtered group is required. Avoid placing conditional logic inside the setter body unless runtime switching is explicitly required.\njusetup[info]{...}\njusetup[abstract/title-style]{...}\njusetup[info]{key=value}
\njusetup[abstract/title-style]{key=value}The njuthesis template uses LaTeX package hooks to manage the transition between template configuration and biblatex initialization. This ensures compatibility whether the user loads biblatex manually or lets the template do it.
Lifecycle Stages:
package/biblatex/before: Triggered before biblatex is loaded. The template releases temporary \addbibresource definitions and passes style options via \PassOptionsToPackage.package/biblatex/after: Triggered after biblatex is loaded. The template executes bibliography options via \ExecuteBibliographyOptions, sets default headings, and imports the collected resource files.env/document/before: A fallback mechanism. If biblatex hasn't been loaded yet, the template executes \RequirePackage{biblatex} here.The NJU Thesis template distinguishes between two types of configuration:
Class Options: These are defined under the internal nju / option namespace. They are processed early during document class loading and are used for critical decisions like package loading, selecting the thesis type (.def files), and registering cover page hooks. Examples include anonymous or type.
User Settings: These are managed via the public nju namespace (e.g., info, image, bib, math) and are typically configured using the \njusetup command. These are intended for content-related settings rather than structural document class decisions.
This separation prevents naming conflicts (e.g., a class option type vs. a module setting theorem/type) and ensures that structural decisions are finalized before user-level settings are applied.
The jusetup command is designed to respect group filtering (e.g., for blind reviews). To ensure that filtering works for nested modules, the command avoids using helper functions like .meta:nn for expansion, as those can bypass group-based filtering by using internal setters. Instead, it relies on a normalized top-level assignment to the nju namespace, ensuring that any exclusion rules applied to the nju group are correctly inherited by sub-modules.
The repository is organized into several functional areas:
source/njuthesis.dtx: The primary source file containing the implementation code, user manual, docstrip guards, class code, and generated .def sections.source/latexmkrc: Configuration for latexmk compilation.source/nju-emblem-*.pdf & source/nju-name-*.pdf: NJU logos (black and purple versions).build.lua: Configuration for l3build (unpacking, installation, checking, CTAN packaging).scripts/download.sh: Downloads and verifies the TeX Live package database.scripts/main.py: Calculates and installs dependency closures.Files in build/ or files generated from the .dtx (like njuthesis.cls or *.def files in a working directory) are secondary outputs. You should edit the .dtx or your own .tex files, not these generated artifacts.
The template provides integrated support for biblatex.
Usage Patterns:
biblatex=false to completely exit the integration.bib/style, bib/option, and bib/resource within \njusetup to control bibliography behavior.package/biblatex/before|after) and environment hooks (env/document/before) to manage the loading sequence. If you load biblatex manually, be aware of these internal hook boundaries.The njuthesis template is built using expl3 and is based on the ctexbook class. It uses an l3keys options system and xtemplate for page and element instances.
Key architectural components include:
.def files are loaded $\rightarrow$ \njusetup is called $\rightarrow$ deferred hooks are executed.\includegraphics, supporting different color choices via \nju-logo-color, \nju-emblem, and \nju-name keys.