OpenGlyph

Version 0.2.1 (2026-10-28), CTAN submission candidate. Maintainer: Zejia FAN.

OpenGlyph provides named, font-backed historical Chinese glyphs for LaTeX. Use an ASCII identifier instead of pasting a missing-character image into a paper. An optional offline compiler constructs new forms by editing named component occurrences and produces OpenType fonts for ordinary typesetting.

The distribution includes 22,583 GlyphWiki ebag_s forms and 38,462 source and dependency programs. It does not identify characters, establish readings, or replace human comparison with the source document. Example new forms are synthetic editing demonstrations, not claims about historical attestations.

Repository and issue tracker: https://github.com/Open-Glyph/OpenGlyph-LaTeX

Requirements and quick start

Typesetting requires XeLaTeX or LuaLaTeX, LaTeX2ε dated 2020-10-01 or newer, and fontspec, iftex and xparse. The Chinese example additionally needs ctex and Fandol (and LuaTeX-ja when using LuaLaTeX). pdfLaTeX is not supported. Ordinary typesetting is offline: no account, model, Python, Node.js or shell escape is used.

After installing the package:

\documentclass{article}
\usepackage{openglyph}
\OpenGlyphLoad{ebag}
\begin{document}
An existing form: \ebag{s030-067}.
\end{document}

Built-in IDs are source identifiers, not scholarly identifications or standard Unicode assignments. PUA addresses are font-local. A PDF embeds its font; sharing editable source requires sharing the matching font bundle as well.

Installation

This ZIP is a browsing-friendly source distribution, not a TDS ZIP. Map files to a personal TEXMF tree as follows (replace TEXMFHOME with the output of kpsewhich -var-value=TEXMFHOME):

Refresh your TeX distribution's filename database if it uses one. Do not copy the example catalog.tex files to the global TeX runtime path. Only the two files under tex/ are runtime TeX files. The offline builder remains optional source tooling, with no PATH wrapper or shell-escape whitelist requested. TeX Live does not install its Python/Node dependencies for you.

For a project-local or Overleaf installation, put the two files from tex/ and fonts/OpenGlyphEbag.otf beside your main .tex file. Select XeLaTeX or LuaLaTeX. The original layout with ebag/catalog.tex and its adjacent font is also supported; a local ebag/ bundle takes precedence over the installed one. Do not combine different built-in bundle versions within one document. Custom bundles require an explicit relative or absolute directory path; finding only their catalogue through an unrelated TEXINPUTS search path is not supported. The font must remain in the same bundle directory.

See doc/openglyph-doc.pdf and its editable source for the full interface. doc/openglyph-example.tex is a Chinese worked example. Open doc/openglyph-index.html for the offline glyph index in the unpacked archive. If you relocate this index, keep its OTF reference consistent; it uses ../fonts/OpenGlyphEbag.otf in this archive.

Constructing new forms (optional)

In the source/ directory, prepare Python 3.10+ and Node.js, and install requirements-build.txt in your own virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-build.txt
python scripts/openglyph.py inspect ebag:s030-067 --node r4 -o preview
python scripts/openglyph.py build examples/newforms.json -o myglyphs
python scripts/openglyph.py build examples/modules.json -o moduleglyphs

On Windows, activate with .venv\Scripts\Activate.ps1 instead. Output folders must be new; existing folders are never overwritten. Copy the resulting myglyphs/ beside the paper, load \OpenGlyphLoad{myglyphs}, and typeset \gwglyph{my:n2}. Pass --allocation old-bundle/allocation.json on revision to preserve prior PUA slots; retired slots are not reused.

High-level JSON supports replace, insert, drop, place, move, group, reusable modules, and source-record select. Nodes are occurrence paths obtained from inspect, not guessed stroke numbers. See the manual and JSON examples. Optional remote image retrieval is a separate toolchain; the LaTeX package does not itself run image recognition or contact OpenGlyph services.

Licenses and source

• OpenGlyph's own code and documentation: MIT, see LICENSE.
• GlyphWiki source data, derived fonts and illustrative derivatives: the retained permissive GlyphWiki grant in source/licenses/GlyphWiki.txt. These files are not relicensed as MIT or OFL.
• Vendored KAGE JavaScript: GPL v3, see source/vendor/kage-engine/COPYING; the original source is included.

See THIRD-PARTY-NOTICES.md for the exact file groups and provenance. source/data/provenance.json and ebag-manifest.json record source hashes, per-glyph information and font addresses. No SEAL font, private paper, scan, local unverified IDS annotation table, credential or user upload is included.

Development and this candidate's documentation are substantially AI-assisted; see AI-ASSISTANCE.md. Human review is not certified by a successful build. This candidate has not been submitted to or accepted by CTAN, TeX Live or MiKTeX. Their review and distribution decisions are separate.