### expl3 Function Examples with Module Prefixes

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Typical examples of expl3 functions found in different modules, illustrating the use of module prefixes in function names.

```tex
\ctex_define_option:n
```

```tex
\xeCJK_check_single_env:nnNn
```

```tex
\CJKtu_char_to_unicode:n
```

```tex
\__ctxdoc_version_zfill:wnnn
```

--------------------------------

### Code Reference Format Example

Source: https://github.com/ctex-org/ctex-kit/blob/master/AGENTS.md

Demonstrates the preferred method for referencing code within documentation, using a concise path and function/method notation. Avoids pasting large code blocks.

```text
# Good - Reference format
`src/auth/jwt.js` (generateToken, verifyToken): Handles JWT creation and validation
```

--------------------------------

### Use ctexart Document Class

Source: https://github.com/ctex-org/ctex-kit/blob/master/README.md

Example of using the `ctexart` document class for Chinese LaTeX documents. This is a straightforward way to start a new document with CTeX support.

```latex
\documentclass{ctexart}
\begin{document}
你好，\LaTeX{}！
\end{document}
```

--------------------------------

### Upload to CTAN using l3build

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/guides/release-workflow.md

This job uploads the package to CTAN. It requires a minimal TeX Live installation, downloads the announcement artifact, renames the GitHub Release zip, and validates the announcement note length. The upload is performed using 'l3build upload', with options for dry-run and email configuration via environment variables.

```bash
      - name: Upload to CTAN
        if: github.ref == 'refs/heads/main'
        env:
          CTAN_UPLOADER: ${{ secrets.CTAN_UPLOADER }}
          CTAN_EMAIL: ${{ secrets.CTAN_EMAIL }}
          CTAN_NOTE: ${{ env.CTAN_NOTE }}
        run: |
          # Install minimal TeX Live
          tlmgr install l3build luatex
          # Download announcement artifact
          gh release download ${{ github.ref_name }} --pattern '*.zip'
          # Rename zip file for l3build
          mv *.zip ${{ env.MODULE }}-ctan.zip
          # Validate note length (max 4096 bytes)
          NOTE_LEN=$(echo -n "${{ env.CTAN_NOTE }}" | wc -c)
          if [ "$NOTE_LEN" -gt 4096 ]; then
            echo "CTAN note exceeds 4096 bytes ($NOTE_LEN bytes)."
            exit 1
          fi
          # Upload to CTAN
          cd ${{ env.MODULE }} && l3build upload --file ../announcement.md --email "$CTAN_EMAIL" --dry-run
```

```bash
      - name: Upload to CTAN
        if: github.ref == 'refs/heads/main'
        env:
          CTAN_UPLOADER: ${{ secrets.CTAN_UPLOADER }}
          CTAN_EMAIL: ${{ secrets.CTAN_EMAIL }}
          CTAN_NOTE: ${{ env.CTAN_NOTE }}
        run: |
          tlmgr install l3build luatex
          gh release download ${{ github.ref_name }} --pattern '*.zip'
          mv *.zip ${{ env.MODULE }}-ctan.zip
          NOTE_LEN=$(echo -n "${{ env.CTAN_NOTE }}" | wc -c)
          if [ "$NOTE_LEN" -gt 4096 ]; then
            echo "CTAN note exceeds 4096 bytes ($NOTE_LEN bytes)."
            exit 1
          fi
          cd ${{ env.MODULE }} && l3build upload --file ../announcement.md --email "$CTAN_EMAIL"
```

--------------------------------

### e-type Expansion Variant Preference

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Examples demonstrating the preference for e-type expansion variants over x-type, following l3kernel recommendations.

```tex
\tl_set:Ne
```

```tex
\tl_set:Nx
```

```tex
\exp_args:Nne
```

```tex
\exp_args:Nnx
```

--------------------------------

### expl3 Private Namespace '@@'

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Examples of the '@@' private namespace convention used for module-internal implementation details.

```tex
\@@_calc_kerning_margin:NN
```

--------------------------------

### expl3 Parameter Signatures

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Examples of expl3 parameter signatures, which are a stable retrieval clue and part of the function's interface.

```tex
:n
```

```tex
:nn
```

```tex
:Nn
```

```tex
:nnNn
```

--------------------------------

### Run Ghostscript for Bounding Box Calculation

Source: https://github.com/ctex-org/ctex-kit/blob/master/CJKpunct/setpunct/setpunct-main.tex

This command uses gswin32c.exe to process a PDF file and calculate its bounding box, outputting the result to a .tex file. Ensure Ghostscript is installed and accessible in your system's PATH.

```shell
gswin32c.exe -dBATCH -dEPSCrop -dNOPAUSE
 -sDEVICE=bbox rubisha.pdf 2>rubishb.tex
```

--------------------------------

### Use ctex Package with Standard Document Class

Source: https://github.com/ctex-org/ctex-kit/blob/master/README.md

Example of using the `ctex` package with a standard document class like `article`. This approach allows for integrating CTeX features into existing document structures.

```latex
\documentclass{article}
\usepackage{ctex}
\begin{document}
你好，\LaTeX{}！
\end{document}
```

--------------------------------

### Hook Timing for Capturing \let-Bound Behavior

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/931-biblatex-pagetracker-let-shadow.md

Illustrates the three hook timings and their effectiveness in capturing \let-bound styles and \Require*Style loads. \@@_at_end_preamble:n and \@@_after_preamble:n are necessary when \let is used within package styles.

```tex
\@@_package_hook:nn { pkg } | `package/pkg/after` = pkg 主 sty 加载完 | ✗（`.bbx` 已加载完，`\let` 已定型；但可以覆盖 sty 定义） | ✓
```

```tex
\@@_at_end_preamble:n | `begindocument/before` | ✓ | ✓（更晚，任何 sty 都能改）
```

```tex
\@@_after_preamble:n | `begindocument/end` | ✓ | ✓
```

--------------------------------

### Build Metric Files with Lua

Source: https://github.com/ctex-org/ctex-kit/blob/master/zhmetrics-uptex/README.md

Run this command in the source directory to generate the metric files.

```shell
texlua makemetrics.lua
```

--------------------------------

### Local Testing of CTAN Upload

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/guides/release-workflow.md

This command demonstrates how to manually test the CTAN upload process locally. It requires setting environment variables for the uploader and email, and placing the downloaded zip file in the correct directory. The `--dry-run` flag is used for testing without actually uploading.

```bash
export CTAN_UPLOADER="Liam Huang"
export CTAN_EMAIL="liamhuang0205@gmail.com"
# 可选: 给 CTAN reviewer 的内部备注 (≤4096 byte), 不设则不写 note 字段
# export CTAN_NOTE="Maintainer changed from ... to ..."
# 把 GH Release 上下载的 zip 改名为 <module>-ctan.zip 放在包目录
cd xeCJK && l3build upload --dry-run --file ../announcement.md
```

--------------------------------

### Bad Code Reference Example

Source: https://github.com/ctex-org/ctex-kit/blob/master/AGENTS.md

Illustrates an discouraged method of referencing code by pasting entire code blocks, which is considered verbose and less maintainable.

```javascript
function generateToken(payload) {
  // ... 50 lines of code
}
```

--------------------------------

### LLM Doc Directory Structure

Source: https://github.com/ctex-org/ctex-kit/blob/master/AGENTS.md

Illustrates the hierarchical organization of documentation files within the `llmdoc/` directory. This structure guides users to the most relevant information for understanding, modifying, or contributing to the project.

```tree
llmdoc/
├── index.md              # START HERE - Navigation and overview
├── overview/             # "What is this project?"
│   └── project-overview.md
├── architecture/         # "How does it work?" (LLM Retrieval Map)
│   └── *.md
├── guides/               # "How do I do X?"
│   └── *.md
└── reference/            # "What are the specifics?"
    └── *.md
```

--------------------------------

### verify-doc-output.sh 脚本逻辑

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/935-check-doc-zhspacing-blockers.md

此脚本用于逐个验证生成的 PDF 文件，确保其存在、具有正确的 PDF magic 字节，并且大小符合最小要求，以防止因编译错误而产生的无效文件。

```bash
scripts/verify-doc-output.sh
```

--------------------------------

### Run xeCJK Test Suite

Source: https://github.com/ctex-org/ctex-kit/blob/master/README.md

Command to run the test suite for the `xeCJK` package using the l3build framework. This verifies the functionality of XeLaTeX CJK support.

```bash
cd xeCJK
l3build check
```

--------------------------------

### xpinyin 包字体配置

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/935-check-doc-zhspacing-blockers.md

为 xpinyin 包添加 fontconfig 配置文件，使 XeLaTeX 能够找到 TeX Gyre Adventor 字体。此配置会扫描 TeX Live 的 opentype 和 truetype 目录。

```bash
workflow 加 /etc/fonts/conf.d/09-texlive-opentype.conf
```

--------------------------------

### xeCJK Setup for Punctuation Measurement Fix

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/architecture/xecjk-architecture.md

Enables the experimental punctuation measurement fix in xeCJK. This option modifies how punctuation spacing is handled, particularly at the end of paragraphs, to prevent issues with measurement macros.

```latex
\xeCJKsetup{experiment/punct-measure-fix}
```

--------------------------------

### Workflow for Working with LLM Docs

Source: https://github.com/ctex-org/ctex-kit/blob/master/AGENTS.md

Outlines the essential steps to follow before writing or modifying code, emphasizing the initial check for and consultation of `llmdoc/`.

```text
1. Check: Does llmdoc/ exist?
   - YES → Read index.md, then relevant docs
   - NO  → Proceed with caution, suggest initializing docs

2. Find relevant architecture docs for the area you're modifying

3. Check guides/ for existing workflows

4. Review reference/ for conventions to follow
```

--------------------------------

### zhmetrics 包 TFM/MAP 文件生成

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/935-check-doc-zhspacing-blockers.md

为 zhmetrics 包添加预处理步骤，使用包内的 Lua 脚本生成缺失的顶层 tfm 和 map 文件，并将其安装到 TEXMFHOME 目录。同时，更新了 tl_packages 以包含 pltotf 工具。

```bash
workflow 加 pkg==zhmetrics pre-doc step
```

```bash
.github/tl_packages 补 fontware
```

--------------------------------

### Docstrip Tagging System in ctex-kit

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

The ctex-kit project utilizes the docstrip tagging system to generate multiple outputs from a single .dtx file, including .sty, .cls, .def files, example files, and documentation. Ensure correct tag selection when modifying .dtx files to avoid unintended consequences.

```tex
%<*pdftex|xetex>
```

--------------------------------

### Run all tests with l3build

Source: https://github.com/ctex-org/ctex-kit/blob/master/README-en.md

Ensure all relevant tests pass by running the l3build check command. This is a prerequisite for submitting code changes.

```bash
l3build check
```

--------------------------------

### CTeX Kit xeCJK/build.lua:1-179

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/overview/project-overview.md

This snippet shows the build configuration for the `xeCJK` package using `l3build`.

```lua
xeCJK/build.lua:1-179
```

--------------------------------

### expl3 Command Scoping: Global Definition

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Demonstrates a global definition using \cs_new_protected:Npx, which persists outside of TeX groups.

```tex
\cs_new_protected:Npx
```

--------------------------------

### Handling \write Whatsits in \@@_recover_glue_whatsit:

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/931-biblatex-pagetracker-let-shadow.md

Addresses a specific scenario where \write whatsits, such as those used by biblatex's \abx@aux@page, can trigger the default branch of \@@_recover_glue_whatsit:. A package-specific patch is preferred over a general narrowing of the default branch due to consistency validation costs.

```tex
`\write` whatsit（`biblatex \abx@aux@page` / `l3doc \codeline@wrindex`）
```

--------------------------------

### Run ctex Test Suite

Source: https://github.com/ctex-org/ctex-kit/blob/master/README.md

Command to run the test suite for the `ctex` package using the l3build framework. Ensure all tests pass before submitting code changes.

```bash
cd ctex
l3build check
```

--------------------------------

### CTeX Kit support/build-config.lua:1-215

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/overview/project-overview.md

This snippet shows the project-level build configuration and hooks shared by modern sub-packages.

```lua
support/build-config.lua:1-215
```

--------------------------------

### zhspacing 包宏定义错误

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/935-check-doc-zhspacing-blockers.md

在修复字体问题后，编译过程暴露了 zhspacing.sty 内部的宏定义错误，表现为 `! Undefined control sequence.` 错误，并且在 `
ewfontfamily` 替换为 `
enewfontfamily` 后，`l.17 
hspacing` 命令展开时找不到 `
hnil` 或 `
hiforloop`。

```latex
! Undefined control sequence.
<argument> \@nil
l.17 \zhspacing
... 
! File ended while scanning use of \@iforloop.
```

--------------------------------

### expl3 Command Scoping: Local Definition

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/coding-conventions.md

Demonstrates a local definition using \cs_set_protected:Npx, which is scoped to the current TeX group.

```tex
\cs_set_protected:Npx
```

--------------------------------

### CTeX Kit .github/workflows/test.yml

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/overview/project-overview.md

This snippet shows the CI configuration for the CTeX Kit project, including platforms and triggers.

```yaml
.github/workflows/test.yml configures Ubuntu, macOS, and Windows platform CI, executing on push, pull request, schedule, and manual triggers, see `.github/workflows/test.yml`.
```

--------------------------------

### Capturing Node Information After Hbox Construction

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/memory/reflections/671-cjkpunct-rglue-nobreak.md

To reliably capture node information like `\lastpenalty` within an `\hbox_set:Nn` context, first construct the hbox, then expand it using `\unhbox` into a new hlist, and finally extract the desired node type. This method accounts for CJK tracking kerns potentially added via `\aftergroup`.

```tex
\setbox0=\hbox{ 测。 }
\setbox2=\hbox{\unhbox0 \unkern\unkern\unskip \xdef\temp{\the\lastpenalty}}
```

--------------------------------

### Run Contribution Tests

Source: https://github.com/ctex-org/ctex-kit/blob/master/llmdoc/reference/build-and-test.md

Execute regression tests for contribution packages using a specific configuration file. This is a stable downstream entry point for verifying cross-package template regressions.

```bash
l3build check -c test/config-contrib -q
```