# 工尺谱示例

`luatex-cn` 自 v0.3.8 起支持工尺谱排版（issue [#90](https://github.com/open-guji/luatex-cn/issues/90)）。

## 文件清单

### 完整示例

| 文件 | 模板 | 说明 |
|------|------|------|
| `圣世呈符.tex` | `ltc-guji` 默认（带网格边框）+ 12 字/列 | 印本复刻 — 鹊桥仙·圣世呈符（基于 ref-2） |
| `西厢记佳期.tex` | `[红楼梦甲戌本]ltc-guji`（无网格、手写本风格）+ 18 字/列 | 手写本近似复刻 — 西厢记·佳期·临镜序（基于 ref-1） |

每个 .tex 都附 `.pdf` 编译输出和 `*-预览.png` 首页预览。

#### 模板选择

- **印本类**（如 ref-2）：用默认 `ltc-guji` 配 `\contentSetup{n-char-per-col=12, n-column=8}`，
  保留细网格线、12 字/列接近木刻印本密度。
- **手写本类**（如 ref-1）：用 `\documentclass[红楼梦甲戌本]{ltc-guji}`，无网格、字间紧密，
  接近抄本质感。草书字体本项目暂无法复刻，只能用 TW-Kai 印刷体替代。

### 参考样本

| 文件 | 来源 | 风格 |
|------|------|------|
| `ref-1-upright.png` | 明清手写本《西厢记·佳期》 | 草书手写，红色板眼 |
| `ref-2-upright.png` | 印本《鹊桥仙·圣世呈符》 | 印刷体，简洁 |
| `ref-3-upright.png` | 现代铅印本 | 书页拍照 |

### 已对齐 vs 参考样本

基于 ref-1 / ref-2 逐字比对：

| 元素 | 圣世呈符 vs ref-2 | 西厢记佳期 vs ref-1 |
|------|---|---|
| 主字字符 | ✅ 全繁体匹配 | ✅ 全繁体匹配 |
| 多 gongche 字串（1-3 字） | ✅ 位置正确 | ✅ |
| 板眼（红色小圆点） | ✅ 位置正确，颜色一致 | ✅ |
| 子标题独占一列 | ✅ `\换行` 实现 | ✅ |
| 短句列内连续流动 | ✅ 移除空行后多句同列 | ✅ |
| 句/韵 句读 | ✅ `\句` `\韵` 在流内（小字） | — (西厢以 `\句读字{原來}`) |
| 调名/曲牌 | ✅ `\调名注{一名廣寒秋}` | ✅ `\宫调{仙吕調}` |
| 列容量 | ✅ 12 字/列 匹配印本密度 | ✅ 18 字/列 匹配抄本密度 |
| 网格边框 | ✅ 细线（默认 ltc-guji） | ✅ 无边框（红楼梦甲戌本） |

### 仍存在的差异

1. **草书字体不可复刻** — ref-1 是明清手写草书，本项目用印刷体 (TW-Kai) 近似。
   要真正复刻需要专用草书 OpenType 字体。
2. **gongche 与主字垂直对齐基准** — 印本中 gongche 字串顶端与主字顶端齐；
   我们当前是垂直居中。轻微不同但视觉差距小。
3. **gongche 横向间距** — 印本中 gongche 紧贴主字右沿；
   我们留了一点 gap (base_size * 0.05)，可微调。
4. **工尺音字精确度** — 部分原图 gongche 难辨（尤其 ref-1 草书），
   .tex 中音字仅取近似/常见值，非考据。
5. **板眼位置** — 印本中板眼位置（字左/字右/字间）随谱本而异；
   我们统一在 gongche 字右侧（xshift=-0.5em）。

## API 速查

### `\工尺{主字}{右侧工尺串}`

主字 + 右侧工尺旁注（Level 1，纯字符串模式）。

```latex
\工尺{春}{尺工}        % 1 主字 + 2 工尺音
\工尺{眠}{六五四}       % 1 主字 + 3 工尺音
```

### `\工尺[opts]{主字}{右侧}`

可选参数：

| 键 | 含义 | 默认 |
|---|---|---|
| `缩放` (`scale`) | 工尺字相对主字的大小 | 0.5 |
| `颜色` (`color`) | 工尺字颜色 | black |
| `偏移` (`offset`) | 与主字的水平间距 | 0pt |

```latex
\工尺[缩放=0.6, 颜色=blue]{大}{尺工}
```

### `\工尺设置{...}`

全局默认值（同上键）。

```latex
\工尺设置{颜色=black, 缩放=0.55}
```

### `\音[<options>]{字}`

工尺字 + 两个正交装饰槽位（板眼 / 八度），可同时启用。仅在 `\工尺` 的右侧参数内使用。

#### 板眼槽位（rhythm slot）

| 预设 | 效果 |
|------|------|
| `\音{尺}` | 工尺字，无标记 |
| `\音[板]{尺}` | 红色 `。` 板点（重拍） |
| `\音[眼]{尺}` | 红色 `、` 眼点（轻拍） |
| `\音[头板]{尺}` | 红色 `×` 头板 |
| `\音[底板]{尺}` | 红色 `└` 底板（休止） |
| `\音[底叮]{尺}` | 红色 `⌐` 底叮 |

#### 八度槽位（octave slot）

| 预设 | 效果 | 出处 |
|------|------|------|
| `\音[高]{尺}` | `亻` 前缀（高八度） | 闽剧 / 粤剧 |
| `\音[低]{尺}` | `彳` 前缀（低八度） | 粤剧 |
| `\音[昆低]{尺}` | `⌒` 钩（低八度） | 昆曲 |

#### 组合与覆盖

```latex
% 板 + 高 同时使用 (双槽位)
\音[板, 高]{尺}

% 颜色/缩放/字符 默认作用于板眼槽位
\音[板, 颜色=blue]{尺}                      % 蓝色板点
\音[字符=●, 缩放=0.3, 颜色=green]{尺}        % 完全自定义板眼

% 八度槽位用专用键 八度颜色 / 八度字符 / 八度缩放 覆盖
\音[高, 八度颜色=blue]{尺}                  % 蓝色 亻
\音[八度字符=亻, 八度颜色=green]{尺}         % 完全自定义八度
```

### `\拖音[<rhythm>]`

延音线 — 单个续拍单元（用 `丨` 字符占位）。继承所有 `\音` 的板眼/八度选项。

```latex
% 4 拍长音 — 第 1 拍发声 + 3 拍延续
\工尺{春}{\音[板]{尺}\拖音[眼]\拖音[板]\拖音[眼]}

% 简单 1 拍延音 (无板眼)
\工尺{延}{\音{尺}\拖音}
```

每个 `\拖音` 占一个 unit 高度，渲染为一根细竖线，自然堆叠在前一个工尺字下方。

### 完整示例

```latex
\工尺{春}{\音[板]{尺}\音[眼]{工}}%
\工尺{眠}{\音[板]{六}}%
\工尺{不}{\音[眼]{五}\音[板]{尺}}%
\工尺{觉}{\音[眼]{工}}%
\工尺{晓}{\音[板]{六}\音[眼]{五}}
```

## 设计参考

- 三张 `ref-*.png` 来自 issue #90。
- 排版规则参考 [维基百科·工尺谱](https://zh.wikipedia.org/zh-cn/工尺谱)。

## 编译

```bash
lualatex 春眠工尺谱.tex
```

需要 `luatex-cn` v0.3.8 或更高版本。
