# 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, LaTeX2e 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:

```tex
\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`):

| This archive | Personal TEXMF destination |
| --- | --- |
| `tex/openglyph.sty` | `tex/latex/openglyph/openglyph.sty` |
| `tex/openglyph-ebag.def` | `tex/latex/openglyph/openglyph-ebag.def` |
| `fonts/OpenGlyphEbag.otf` | `fonts/opentype/public/openglyph/OpenGlyphEbag.otf` |
| `doc/` | `doc/latex/openglyph/` (preserve structure) |
| `source/` | `source/latex/openglyph/` (preserve structure) |
| root README, LICENSE, notices, disclosure, changelog | `doc/latex/openglyph/` |

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:

```sh
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.