DOCSEARCHbyAlgolia
Submit Docs

CTeX-kit Documentation

repository·master·Indexed 21 days ago

https://github.com/ctex-org/ctex-kit

A comprehensive infrastructure for Chinese typesetting in TeX, providing packages, scripts, and resources for engines including XeLaTeX, LuaLaTeX, upLaTeX, and pdfLaTeX. It includes the ctex package and ctexart document class, as well as specialized tools like zhlineskip for CJK line spacing, zhmetrics-uptex for upTeX font metrics, and zhspacing for XeTeX. The kit provides a unified entry point for Chinese LaTeX workflows, managing font sets, heading schemes, and font size systems via the \ctexset and \zihao commands.

Tokens
83.8K
Snippets
137
Records
429
Agent score
77%

What's inside CTeX-kit

  1. What is zhmetrics-uptex

    master
    The zhmetrics-uptex package provides Chinese font metrics for the upTeX engine, including JFM (Japanese Font Metric) and VF (Virtual Font) files. It also includes a DVIPDFMx font mapping specifically for Fandol fonts. This allows the DVIPDFMx output driver to correctly handle Fandol fonts when using upTeX.

  3. Overview of CTeX-kit

    master
    CTeX-kit is a collection of packages, scripts, and resources designed for Chinese TeX users. It provides a complete typesetting infrastructure for Chinese LaTeX workflows, aiming to offer unified and reliable Chinese typesetting support across different TeX engines. The project is maintained by the CTeX community and includes several technical paths such as ctex, xeCJK, and zhspacing.

  4. Overview of the zhlineskip package

    master

    The zhlineskip package is designed for typesetting CJK (Chinese, Japanese, Korean) documents. It provides fine-grained control over line spacing (leading) by allowing users to define two specific ratios:

    1. Body text ratio: The ratio between the leading and the font size of the main body text.
    2. Footnote text ratio: The ratio between the leading and the font size of footnote text.

    Key features include:

    • CJK-optimized spacing: While Latin typography typically uses ratios between 1.2 and 1.45, zhlineskip supports the larger ratios (usually 1.5 to 1.67) required for CJK typography.
    • Math formula handling: It can automatically restore math formula leading to match Latin typography standards, preventing math from inheriting the larger CJK line spacing.
    • Microsoft Word compatibility: It enables users to achieve the "Microsoft Word multiple line spacing" style within LaTeX.

  5. Understand the CTeX-kit project structure

    master

    CTeX-kit is a monorepo containing a collection of packages, scripts, and resources for Chinese typesetting in TeX/LaTeX/ConTeXt. The repository is organized into several directories representing different packages and tools.

    Core Packages:

    • ctex/: The main entry point providing unified Chinese document classes and macro sets. It is composed of several .dtx files (ctex.dtx, ctex-kernel.dtx, ctex-auxpkg.dtx, ctex-engine.dtx, ctex-scheme.dtx, and ctex-fontset.dtx).
    • xeCJK/: Provides Chinese font, spacing, and punctuation support specifically for XeTeX/XeLaTeX engines.

    Satellite Packages & Tools:

    • Traditional CJK enhancements: CJKpunct/, xCJK2uni/, gbkmac/, gbk2uni/.
    • Specialized features: zhnumber/ (numbers), xpinyin/ (pinyin), jiazhu/ (annotations).
    • Spacing and metrics: zhlineskip/, zhspacing/, zh-luatex/, zhmetrics/, zhmetrics-uptex/.
    • Templates: templates/.

  6. Understand the xeCJK source organization

    master

    The core of xeCJK is contained in xeCJK/xeCJK.dtx (~16,000 lines), which is processed via docstrip to generate the following files:

    • xeCJK.sty: The main package.
    • xeCJK.cfg: Default configuration.
    • xeCJKfntef.sty: Provides text effects like underlines and emphasis marks.
    • xeCJK-listings.sty: A compatibility layer for the listings package.
    • xunicode-addon.sty: Supplements xunicode symbols.

  7. Understand the CI/CD workflow and gatekeeping

    master

    The project uses several GitHub Actions workflows to ensure code quality and prevent regressions. Key workflows include:

    • test.yml: Cross-platform testing (Ubuntu, macOS, Windows) for core packages.
    • check-doc.yml: A PR gatekeeper that runs l3build doc to verify that documentation (.dtx files) can successfully compile to PDF.
    • check-tag.yml: Verifies that the version stamp in source files is synchronized with the build.lua version for supported packages.
    • check-changelog.yml: Ensures CHANGELOG.md entries are synchronized with the \changes entries in .dtx files.
    • lint-test-files.yml: Lints .lvt test files to prevent misuse of the tilde (~) character within specific LaTeX command blocks.
    • release.yml: Automates the creation of GitHub pre-releases when specific tags (e.g., ctex-v*) are pushed.
    • release-ctan-upload.yml: Handles formal CTAN delivery via workflow_dispatch.

  8. Use gbkmac.tex for CJK Type1 fonts

    master
    The gbkmac.tex file provides support for CJK Type1 fonts in plain TeX. It is designed for use with pdftex or the tex + dvipdfmx workflow. This is useful when you need to handle Chinese character encoding within these specific TeX engines using Type1 fonts.

  9. What is xeCJK and its role in CTeX

    master

    xeCJK is the Chinese typesetting engine for XeLaTeX. It is not a standalone system but a character spacing and font control layer built on top of the XeTeX interchar token primitive.

    Its primary responsibilities include:

    1. Using different fonts for CJK (Chinese, Japanese, Korean) and Western characters.
    2. Automatically ignoring source code spaces between CJK characters.
    3. Managing compression and squeezing styles for full-width punctuation.
    4. Automatically inserting appropriate spacing between CJK and Western characters.

    In the CTeX ecosystem, ctex serves as the unified user interface, while xeCJK acts as the XeTeX backend implementation.

  10. Coexist with legacy `\CTEX@` interfaces

    master

    The ctex project is not purely expl3; it maintains some legacy LaTeX2e internal interfaces (e.g., \CTEX@char@n).

    When modifying ctex:

    1. Do not assume all internal calls have migrated to expl3.
    2. If a feature is wrapped in both \CTEX@... and \ctex_..., determine which is the compatibility bridge and which is the actual backend. Generally, expl3 is used for new logic and unified option handling, while \CTEX@ handles legacy compatibility and LaTeX2e hooks.