xpinyin: 包功能的模块化

[MathMapMat]

目前 xpinyin 包的功能是直接在汉字上方加拼音, 希望可以把一部分功能拆分出来:

1. 提供一个命令, 返回一个汉字的拼音.
2. 提供一个命令, 返回一个汉字的首字母.
3. 提供一个命令, 返回一个汉字的声母.
4. 提供一个命令, 返回一个汉字的韵母.
   以上命令可提供一个option, 决定是否加声调, 声调直接修饰在字母上还是用数字表示.

提供以上功能以后可以更好的处理中文索引问题.

[muzimuzhi]

提供以上功能以后可以更好的处理中文索引问题.

两者的联系是？能否给个例子

[stone-zeng]

一个粗浅的实现（主要是韵母没有处理，声调的选项也没管）：

% 拼音
\cs_new:Npn \PrintPinyin #1
  { \use:c { c__xpinyin_ \int_to_arabic:n { `#1 } _tl } }

% 首字母
\cs_new_protected:Npn \PrintPinyinAbbr #1
  {
    \tl_set:Nx \l_tmpa_tl { \tl_head:f { \PrintPinyin {#1} } }
    \exp_args:Nx \tl_head:n { \exp_args:NV \char_to_nfd:N \l_tmpa_tl }
  }

% 声母
\cs_new_protected:Npn \PrintPinyinInital #1
  {
    \exp_args:Nf \__pinyin_split:n { \PrintPinyin {#1} }
    \seq_item:Nn \l__pinyin_split_seq {2}
  }

% 韵母
\cs_new_protected:Npn \PrintPinyinFinal #1
  {
    \exp_args:Nf \__pinyin_split:n { \PrintPinyin {#1} }
    \seq_item:Nn \l__pinyin_split_seq {3}
  }

\cs_new_protected:Npn \__pinyin_split:n #1
  {
    \seq_clear:N \l__pinyin_split_seq
    \regex_extract_once:NnN \c__pinyin_split_regex {#1} \l__pinyin_split_seq
  }

\regex_const:Nn \c__pinyin_split_regex { \A ([b|p|m|f|d|t|n|l|g|k|h|j|q|x|r|z|c|s]h?) (.+) \Z }
\seq_new:N \l__pinyin_split_seq

[MathMapMat]

提供以上功能以后可以更好的处理中文索引问题.

两者的联系是？能否给个例子

在我查了一遍 ctan 中各类处理中文索引的 package 后, 我发现的最优解是用 glossaries 和 bib2gls 包.
xindy 包没人写中文 style 文件, 类比韩文的 style 文件已很恐怖, 估计中文处理效率有限.
zhmakeindex 可用, 但还不够好.
bib2gls 可以按 UCA-CLDR 标准处理 Unicode 在各 locale 里的排序.
目前 CLDR 的标准中, 中文和英文是合在一起排序的. 比如说 '汉字' 和 'happy' 都会列在 'H' 条目中.
可以说目前的解决方案已经很不错了, 但是我觉得书里的索引还是把英文和中文分开比较好, 按 符号, A-Z, 汉字拼音A-Z 的顺序.
在没有一个包可以自动处理汉字的拼音首字母的情况下, 需要手动给每个索引项加个前缀, 另加 26 个索引组.
如果可以自动给出汉字的拼音首字母(如果是一串字符的首字符的首字母就更好了), 那么就可以自动加前缀, 只需要建立索引组就行.

[muzimuzhi]

zhmakeindex 可用, 但还不够好.

具体哪里不够好呢？

[MathMapMat]

zhmakeindex 可用, 但还不够好.

具体哪里不够好呢？

多语言同时索引时兼顾中文和非英文文字会有些麻烦. 另外多层级的条目遇到各级都需要指定键和输出值时好像有问题(可能是我没弄清语法, 不过 makeindex 里好像也弄不出来).
我非常感谢 CTeX 的贡献, 并不是有意冒犯.

[MathMapMat]

一个粗浅的实现（主要是韵母没有处理，声调的选项也没管）：

% 拼音
\cs_new:Npn \PrintPinyin #1
  { \use:c { c__xpinyin_ \int_to_arabic:n { `#1 } _tl } }

% 首字母
\cs_new_protected:Npn \PrintPinyinAbbr #1
  {
    \tl_set:Nx \l_tmpa_tl { \tl_head:f { \PrintPinyin {#1} } }
    \exp_args:Nx \tl_head:n { \exp_args:NV \char_to_nfd:N \l_tmpa_tl }
  }

% 声母
\cs_new_protected:Npn \PrintPinyinInital #1
  {
    \exp_args:Nf \__pinyin_split:n { \PrintPinyin {#1} }
    \seq_item:Nn \l__pinyin_split_seq {2}
  }

% 韵母
\cs_new_protected:Npn \PrintPinyinFinal #1
  {
    \exp_args:Nf \__pinyin_split:n { \PrintPinyin {#1} }
    \seq_item:Nn \l__pinyin_split_seq {3}
  }

\cs_new_protected:Npn \__pinyin_split:n #1
  {
    \seq_clear:N \l__pinyin_split_seq
    \regex_extract_once:NnN \c__pinyin_split_regex {#1} \l__pinyin_split_seq
  }

\regex_const:Nn \c__pinyin_split_regex { \A ([b|p|m|f|d|t|n|l|g|k|h|j|q|x|r|z|c|s]h?) (.+) \Z }
\seq_new:N \l__pinyin_split_seq

我对 TeX 的底层实现不太了解, 下面是我用 python 处理声调的方法. 有几个特殊的字音调标在 n 和 m 上.

def tones_to_numbers(s):
	ret = s
	ret = re.sub(r"([a-z]*)ā([a-z]*)", r"\g<1>a\g<2>1", ret)
	ret = re.sub(r"([a-z]*)á([a-z]*)", r"\g<1>a\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ǎ([a-z]*)", r"\g<1>a\g<2>3", ret)
	ret = re.sub(r"([a-z]*)à([a-z]*)", r"\g<1>a\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ō([a-z]*)", r"\g<1>o\g<2>1", ret)
	ret = re.sub(r"([a-z]*)ó([a-z]*)", r"\g<1>o\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ǒ([a-z]*)", r"\g<1>o\g<2>3", ret)
	ret = re.sub(r"([a-z]*)ò([a-z]*)", r"\g<1>o\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ē([a-z]*)", r"\g<1>e\g<2>1", ret)
	ret = re.sub(r"([a-z]*)é([a-z]*)", r"\g<1>e\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ě([a-z]*)", r"\g<1>e\g<2>3", ret)
	ret = re.sub(r"([a-z]*)è([a-z]*)", r"\g<1>e\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ī([a-z]*)", r"\g<1>i\g<2>1", ret)
	ret = re.sub(r"([a-z]*)í([a-z]*)", r"\g<1>i\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ǐ([a-z]*)", r"\g<1>i\g<2>3", ret)
	ret = re.sub(r"([a-z]*)ì([a-z]*)", r"\g<1>i\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ū([a-z]*)", r"\g<1>u\g<2>1", ret)
	ret = re.sub(r"([a-z]*)ú([a-z]*)", r"\g<1>u\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ǔ([a-z]*)", r"\g<1>u\g<2>3", ret)
	ret = re.sub(r"([a-z]*)ù([a-z]*)", r"\g<1>u\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ü([a-z]*)", r"\g<1>v\g<2>", ret)
	ret = re.sub(r"([a-z]*)ǖ([a-z]*)", r"\g<1>v\g<2>1", ret)
	ret = re.sub(r"([a-z]*)ǘ([a-z]*)", r"\g<1>v\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ǚ([a-z]*)", r"\g<1>v\g<2>3", ret)
	ret = re.sub(r"([a-z]*)ǜ([a-z]*)", r"\g<1>v\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ń([a-z]*)", r"\g<1>n\g<2>2", ret)
	ret = re.sub(r"([a-z]*)ň([a-z]*)", r"\g<1>n\g<2>3", ret)
	ret = re.sub(r"([a-z]*)ǹ([a-z]*)", r"\g<1>n\g<2>4", ret)
	ret = re.sub(r"([a-z]*)ḿ([a-z]*)", r"\g<1>m\g<2>2", ret)
	return ret

[Liam0205]

调研结论与设计决策

对这个需求做了一轮调研，把 stone-zeng 五年前给的原型在当前代码上实跑了一遍，统计了整个数据库的相关分布，并逐项确认了几处实现约束。下面记录调研发现和已经确定的设计决策，供后续实现和讨论。

原型的现状

@stone-zeng 的原型在当前代码上仍然可用，四个命令都能出结果：

拼音: zhōng / hàn      首字母: z / h
声母: zh / h           韵母: ōng / àn

数据库的存储形式与原型当初的假设一致（c__xpinyin_<码位>_tl），所以查询能力的数据基础是现成的：44360 个单音字条目，5965 个多音字条目。

但原型有一处需要修正。声母与韵母所用的正则要求必须匹配到声母，因此对以 y、w 或元音开头的拼音会返回空：

安 an:  声母=[] 韵母=[]
王 wang: 声母=[] 韵母=[]
月 yue:  声母=[] 韵母=[]
知 zhi:  声母=[zh] 韵母=[ī]

统计了整个数据库，这类字有 6268 个，占单音字的 14.1%，按开头写法分布为：yi 1344、yu 1095、ya 1072、we 569、a 421、yo 395、e 366、wa 349、wu 284、ye 194、wo 99、o 80。

首字母命令不受这个问题影响，它走的是「取拼音首字符再去掉声调」这条路径。44360 个单音字全部能归入 a 到 z，没有例外，缺的 i、u、v 正是拼音里不作首字母的三个。也就是说 issue 正文提到的索引分组用途，数据上没有缺口。

设计决策

一、四个命令都做

命名为 \xpinyinvalue、\xpinyininitial、\xpinyinshengmu、\xpinyinyunmu。统一用 xpinyin 前缀，与 \xpinyin、\xpinyinsetup 一致，不额外占用全局名字（这四个名字在本包和 TeX Live 里都未被使用）。

声母和韵母用汉语拼音的说法，是为了避开英文 initial 的歧义——它既可以指首字母，也可以指声母，原型里正是用 Abbr 和 Inital 两个词来区分的。

二、y 和 w 的切分提供两种模式

这决定上面那 6268 个字的输出。两种切分方式的结果不同：

字	拼音	字面切分声母	字面切分韵母	国标声母	国标韵母
安	an	∅	an	∅	an
王	wang	w	ang	∅	uang
月	yue	y	ue	∅	üe
鱼	yu	y	u	∅	ü
儿	er	∅	er	∅	er

《汉语拼音方案》里 y 和 w 是介音 i、u、ü 的书写形式，本身不是声母，所以国标一列要把写法还原成音位。还原规则可以机械化：y 后接 i 就去掉 y；y 后接 u 时该 u 实为 ü；y 后接其他元音则 y 变 i；w 后接 u 去掉 w，接其他元音则 w 变 u。

两种切分各有用处，因此都提供，用 scheme 选项切换：

\xpinyinshengmu{王}                   % w
\xpinyinshengmu[scheme=official]{王}  % 空
\xpinyinyunmu{王}                     % ang
\xpinyinyunmu[scheme=official]{王}    % uang

三、默认用字面切分

默认值必须定下来，否则每个调用点都得显式写选项。选字面切分的理由是它不做音位还原，输出可预测，而且声母与韵母拼回去等于原拼音，写测试断言时可以直接比对。国标语义需要显式写 scheme=official。

代价是这个默认值在语言学上不严谨，文档里需要说清楚。

yo 一类（395 个字）在国标模式下按上面的通则处理成 io。这一类的实际读音在语言学上有争议，文档里会标注为已知争议点。

四、多音字默认取首选读音，星号形式取全部

统计发现，5965 个多音字里有 3869 个（64.9%）的不同读音落在不同的首字母组，例如「行」首选 xíng 但也读 háng。所以做索引时归入哪一组不是边缘情况，而是多数情况。

现有的 \xpinyin 默认取首选读音，multiple 选项只用于提醒校对、不改变取值。查询命令沿用这个惯例，另外提供星号形式取全部读音：

\xpinyinvalue{行}     % xíng
\xpinyininitial{行}   % x
\xpinyinvalue*{行}    % háng,hàng,xìng,xíng
\xpinyininitial*{行}  % h,x

需要双收录的场景用星号形式自行展开。

五、声调提供四种形式

issue 正文要求「决定是否加声调，声调直接修饰在字母上还是用数字表示」。用 tone 选项提供四种：

\xpinyinvalue{女}                 % nǚ  （tone=mark，默认）
\xpinyinvalue[tone=number]{女}    % nv3
\xpinyinvalue[tone=none]{女}      % nü
\xpinyinvalue[tone=v]{女}         % nv

实现上有一处需要注意。ü 在 NFD 分解下带两个组合符，分音符加声调符号：

zhōng -> 1声(macron)
nǚ    -> diaeresis(ü), 3声(caron)
lǜ    -> diaeresis(ü), 4声(grave)

所以去掉声调时只能剥掉声调符号而保留分音符，否则 nǚ 会变成 nu 而不是 nü，声母、韵母和索引都会跟着错。issue 正文里那段 Python 代码把 ü 单独映射成 v，处理的正是同一个问题。

六、数字形式下的 ü 写作 v

包里已有先例：\pinyin 的输入约定就是 v，手册里的例子是 \pinyin{nv3hai2zi} 和 \pinyin{lv2zi}，内部由 \@@_replace_v:n 把 v 映射成 ü。数字形式输出 nv3 与这个约定对称，可以直接馈回 \pinyin，即 \pinyin{\xpinyinvalue[tone=number]{女}} 得到 nǚ。

若写成 nu3，馈回 \pinyin 会得到「努」的读音 nǔ 而不是「女」的 nǚ，属于不可逆且错得隐蔽。

七、预生成无调形式，四个命令都可展开

这是技术上最关键的一条。纯查表的拼音命令可以完全展开，\edef、\index 排序键、\csname 三种场景都验证通过。但去掉声调要用 \char_to_nfd:N，它嵌套在可展开的上下文里会直接失败（实测报 100 个错误），只能先把值赋给变量再处理。

而 issue 正文说的索引用途恰恰需要可展开：\index 的排序键、以及 bib2gls 的字段都要求参数能展开成字面文本。

因此在数据库生成阶段就把无调形式和首字母算好存起来，运行时只做查表：

\XPYU {中}{20013}{zhōng}
\XPYUP{20013}{zhong}{z}      % 新增

这样四个命令都可展开，去声调和 ü 的处理在生成期一次性解决，运行时没有额外开销。

八、预生成表按需载入

预生成会让数据库从 1.3 MB 增加到约 2.3 MB。实测当前载入数据库耗时约 0.33 秒、占用 100 万个 string characters（上限 540 万），增加后这两项都会接近翻倍，而只用注音功能的用户并不需要这张表。

所以把无调与首字母表单独放一个文件，用包选项按需载入：

\usepackage{xpinyin}          % 不载入，现有用户不受影响
\usepackage[query]{xpinyin}   % 载入查询表

未写该选项而调用查询命令时给出明确的报错提示。包里已经在用 l3keys2e 和 ProcessKeyOptions，加包选项是现成机制。

九、只支持 Unicode 引擎

xpinyin 同时支持 XeTeX 加 xeCJK 与 pdfTeX 加 CJKutf8 两条路线，包内是两套互不复用的适配。但查询命令要取汉字的码位，实测在 CJKutf8 下：直接用 `#1 完全失效，输出为空；改用包内现有的 \@@_to_unicode:n 会输出乱码并报 10 个错误，因为它依赖 \CJK@plane，需要字符级钩子提供的上下文。

要支持 pdfTeX 得另外设计一套取码位的路径，而这个需求指向的 glossaries 与 bib2gls 本身面向现代引擎。因此这组命令只在 Unicode 引擎下提供，文档中写明这一限制。

测试

计划新增 pinyin-query01.lvt，走 XeTeX 路线。判据是可展开性与各 scheme、tone 组合的字面输出，不用盒子尺寸——查询命令不参与排版，尺寸类断言在这里恒真。

零声母、ü、多音字跨首字母组这三类各自要有用例，它们是三种不同的出错方式，互相不能替代。字面切分模式下「声母加韵母等于原拼音」可以直接写成断言；国标模式不可逆（空加 uang 拼不回 wang），判据需要分开写。

---

以上决策已确认，实现前先在此记录，便于讨论与复核。若对 scheme 的默认值、多音字的星号语义或 yo 一类的处理有不同看法，欢迎在此讨论。

[Liam0205]

temp