@kensio/pinyinjs 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,15 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
 
 ### Added
 
+- **`TEACHING_JIAO` and `COUNTED_MEASURE`,** two more lattice rules, and
+  `QUANTITY_CHARACTERS`, the 汉字 a quantity is written with that the second of
+  them asks about. See the fixes below for what they do and what they measure.
+- **`counts` on the numeral options.** Whether the number stands immediately in
+  front of something it counts, which is what makes a lone 2 两:
+  `numeralHanzi(2, { counts: true })` is `两` and `numeralHanzi(2)` is `二`.
+  Unlike `liang` it is not a variable choice — 二个 is simply wrong — but
+  nothing about the number says whether it is counting, so the caller says.
+  `convert` sets it from the character after the digits.
 - **`SYLLABLE_TONES` and `isAttestedTone`.** Which tones each of the 424
   syllables is actually written in, extracted from the merged dictionary and
   held to it by a build assertion. 424 syllables in five tones would be 2,120
@@ -24,23 +33,81 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   en.wiktionary's Mandarin pronunciation blocks, in bopomofo, Wade-Giles, Yale
   and GR with their tones, and all 50 rows of Wikipedia's _Help:IPA/Mandarin_
   key. The 417-row syllabary already checked was toneless, so it could say
-  nothing about tone marks, the neutral tone, 儿化 or how a word is joined —
+  nothing about tone marks, the neutral tone, 儿化 or how a word is joined,
   which is where the four fixes below were found.
 
 ### Fixed
 
+- **教 was `jiào` even where it was teaching.** 他在北京大学教了三年书 came out
+  `jiàole sān nián shū`, and 我教英语, 谁教你法语 and 她教我如何游泳 with it.
+  The dictionary stores 教 as `jiào` with `jiāo` as an alternate, and `jiào` is
+  right for the compounds — 教育, 教师, 宗教, 主教 — which are words and reach
+  their reading through the word; what is left is the 教 standing as a word of
+  its own, and that one is the verb. The object is what says so: a pronoun, a
+  noun or a name after it, or an aspect particle, since only a verb takes 了,
+  过 or 得. Forcing the character's own reading was not enough on its own,
+  because a two-character reading carries its 教 into the position from
+  outside — 王老师教我们汉语 read `jiào` off 师教 and 来教我 off 来教 — so an
+  untagged pair ending in 教 goes too, while every tagged word keeps its
+  reading: 任教, 宗教, 主教, 佛教, 传教, 执教, 请教, 家教. Over 88,866 lines
+  181 教 decode as a word of their own and every one read `jiào`; 158 are now
+  `jiāo`, three of them wrongly — 统一教创始人, 方法教深思 and 做到了教政分离,
+  where a nominal compound takes an object's shape. CPP's polyphone score is
+  89.05%, up from 89.04%.
+- **A 量词 was swallowed by the word behind it.** 三个人 was `sān gèrén`, three
+  _personals_, because 个人 is a common noun and nothing weighed it against the
+  个 belonging to the 三 in front of it. It is now `sān gè rén`, and so are
+  两家人, 三杯水, 四匹马, 十八层楼 and 一段长时间. What makes it decidable is
+  that the dictionary tags the 量词: 个, 次, 天 and 杯 are `q`, while the
+  characters that only look like measure words in this position are not — 分 is
+  a verb, 部 and 成 are nouns, 年 and 点 are numerals — so 五分钟, 三部分,
+  五成分, 五年级 and 三点钟 are untouched, and those are exactly the words a
+  blanket rule would break. Nor does an ordinal count anything (第三集团军), nor
+  a numeral inside a longer word (唯一道路), and a number and its measure
+  written solid survive whole where the dictionary has them: 一辈子, 一会儿,
+  一口气 and 两口子 are unchanged. Over 88,866 lines the rule forbids 561 edges
+  and moves 53 decodes, three of them wrongly — 一批评, 这一名词 and 六七股灾,
+  where the 一 and the 六七 count nothing. Exactly one reading changes in the
+  whole corpus and it is a fix: 已经下了两天雨了 read 天雨 as `tiān yù`.
+- **The Han after a number was decoded without it.** 2个人 was `liǎng gèrén`
+  while 两个人 written out was already `liǎng gè rén`, because a Han run was
+  decoded on its own and had no idea a number preceded it. A run is now decoded
+  with the 汉字 the digits stand for in front of it, and reported without them,
+  so digits and 汉字 reach the same decode. `decodeRun` and `decodeRunScored`
+  take that context as a fourth argument; where a reading would straddle the
+  join — 1点儿事, whose 一点儿 is one `yìdiǎnr` over both sides of it — the run
+  is decoded alone, as before.
+- **A lone 2 in front of a 量词 was read 二.** 我们买了2个西瓜 came out as
+  `wǒmen mǎile èr gè xīguā`, and a 2 standing immediately in front of what it
+  counts is 两: it is now `liǎng gè`, and 2岁 is `liǎng suì`, 2点 `liǎng diǎn`
+  and 2万人 `liǎng wàn rén`, the same 两 that 2,000 and 2:00 already got. The
+  measure words a 2 can count with are an open list, so 两 is the default and
+  the exceptions are named — 月, 日, 号, 楼, 路, 班 and 期, where the digit
+  labels a position rather than counting (2月 is `èr yuè`), an ordinal, which
+  the 第 in front of it marks (第2次 is `dì èr cì`), and 十 and 百, which follow
+  二 as 20 and 200 already do. A 2 inside a larger number is untouched: 12个 is
+  still `shí'èr gè`.
+- **A decimal lost the grouping of its counted part.** 一共75.5元 was
+  `yígòng qī shí wǔ diǎn wǔ yuán`, with the 75 in loose syllables, and is now
+  `yígòng qīshíwǔ diǎn wǔ yuán`, the same word 一共75元 already got. Only what
+  follows the 点 is read a digit at a time, and that part is unchanged: 3.14 is
+  still `sān diǎn yī sì`, and sandhi still stops at the point.
+- **A decimal point was read as a full stop.** 一共75.5元 came back as
+  `Yígòng …`, capitalised as though the text were a sentence, and a conversion
+  keeping its digits capitalised again after the point: 我有75.5个。was
+  `Wǒ yǒu75.5Gè.` A stop between two digits now ends no sentence.
 - **Bopomofo wrote the tone mark after the 儿化 ㄦ.** 哪儿 nǎr was `ㄋㄚㄦˇ` and
   is now `ㄋㄚˇㄦ`: the mark belongs to the nucleus and the suffix is not part of
   what it marks. A mark written after the ㄦ is still read.
 - **Wade-Giles put the tone digit on the 儿化 suffix,** so 花儿 huār was
-  `hua-êrh¹` — a first-tone 兒. It is now `hua¹-'rh`, with the digit on the
+  `hua-êrh¹`, a first-tone 兒. It is now `hua¹-'rh`, with the digit on the
   syllable the tone belongs to and the suffix written as the reduced `'rh` that
   keeps it apart from 女儿 nǚ'ér's `nü³-êrh²`.
 - **Gwoyeu Romatzyh wrote 儿化 as a plain `-l` suffix.** GR fuses it into the
   rime instead, and the rules are now implemented as _Spelling in Gwoyeu
   Romatzyh_ gives them: 玩儿 wánr is `wal` rather than `wanl`, 事儿 shìr is
   `shell`, 今儿 jīnr is `jiel`. The fusion is many-to-one, so `jiel` is 今儿 and
-  鸡儿 both and 128 forms no longer round-trip — every one of them a form the
+  鸡儿 both and 128 forms no longer round-trip, every one of them a form the
   language does not write.
 - **Gwoyeu Romatzyh wrote `.mhe` for a neutral 么.** The `-h-` is the first tone
   of a sonorant initial, and a neutral syllable is in no tone at all; the basic
@@ -49,22 +116,50 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   follows the broader IPA column of _Comparison of Standard Chinese
   transcription systems_, which is where its ground truth comes from; the two
   pages differ at the medials, -ang, the empty rhyme and the diphthongs. No
-  output changed — the claim did.
+  output changed, only the claim.
 - **`--system ipa` capitalised the IPA.** 我去银行。他姓王。 came out as
   `Uo˨˩˦ ... Tʰa˥ ɕiŋ˥˩ Uaŋ˧˥`, with the sentence capital and the proper noun
   carried over from the pinyin as though a transcription spelled words. IPA
-  letters are symbols rather than an alphabet — `[T]` is not `[t]` in a larger
-  size but a symbol the IPA does not have — so the capitals are now dropped for
+  letters are symbols rather than an alphabet, since `[T]` is not `[t]` in a
+  larger size but a symbol the IPA does not have, so the capitals are now dropped for
   IPA and bopomofo and kept for the three romanisations. `toTranscription`
   takes `{ capitals: false }` for callers writing their own.
+- **A compound lost the zh-TW reading its own parts carry.** 垃圾分類 read
+  `lājīfēnlèi` under `zh-TW`, because CC-CEDICT marks `Taiwan pr.` on 垃圾 and
+  垃圾桶 and on no other compound, and the decoder prefers the longer word, so
+  the entry that had the delta was never consulted. 101 compounds now compose
+  one from their constituents, 垃圾 accounting for 14 of them and 比肩, 玳瑁,
+  从容, 骨头, 蜗牛 and 说服 for most of the rest. Three guards keep it honest:
+  the constituent has to survive segmentation (運行狀況 contains 行狀 but reads
+  運行 + 狀況), it has to be read in the compound exactly as its own entry reads
+  it, and it has to be a whole word rather than a bare character, since 會's `huǐ`
+  would rewrite 三合會 as `sānhéhuǐ` and 3,743 entries would compose that way
+  against the 101 that whole words compose.
+- **A character's zh-TW delta was often a choice between its 普通话 senses.**
+  从容地 read `cōngróng dì` and 他都知道 read `tā dū zhīdào` under `zh-TW`,
+  because 地 was stored with a Taiwan reading of `dì` and 都 with `dū`. Neither
+  is a locale shift: CC-CEDICT lists 地[de5] and 地[di4] as separate entries, so
+  `dì` is what 地 reads in 普通话 when it means the ground, and the adverbial
+  particle is `de` in Taipei too. A delta the word already has as a 普通话 sense
+  is now refused, so 71 characters and 3 words lose one, 都, 着, 应, 差, 称, 斗,
+  舍, 薄 and 万 among them, while 和 `hàn`, 期 `qí`, 垃 `lè` and 髮 `fǎ` stay,
+  no 普通话 sense reading any of those that way. A `Taiwan pr.` note is also
+  only read off a sense matching the reading the entry settled on, which drops
+  16 more: the note on 著's chess-move sense, which reads `zhāo`, had been
+  giving the aspect particle 着 a 國語 reading of `zhuó`.
+- **A locale delta overwrote a reading it was not measured against.** The delta
+  describes the entry's own 普通话 reading, so a polyphone the decode read some
+  other way, such as 得 forced to the modal `děi` rather than the particle `de`
+  its entry stores, now keeps what the decode worked out instead of being
+  rewritten from the entry.
 
 ### Changed
 
 - **Reading a romanisation narrows on the tone that was written.**
   `readWadeGiles("lo²")` was `[luó, ló]` and is now `[luó]`: 咯 is a
   sentence-final particle and is only ever neutral, so ló is not a syllable
-  Mandarin has. The same goes for `readWadeGilesLoosely` — `pan²` is pán alone
-  — and for `readYale`, `readIpa` and `readGwoyeu`, where it settles the 儿化
+  Mandarin has. The same goes for `readWadeGilesLoosely`, where `pan²` is pán
+  alone, and for `readYale`, `readIpa` and `readGwoyeu`, where it settles the 儿化
   collisions the same way (`ell` is 二 èr, there being no first-tone 兒).
   Narrowing never empties a list: a tone no candidate is written in leaves the
   candidates alone, since that says the tone is wrong rather than the spelling.
@@ -86,7 +181,7 @@ decoder internals and the build pipeline.
 - **Transcription systems, all five, in both directions.** Bopomofo, Wade-Giles,
   Yale, Gwoyeu Romatzyh and IPA at the syllable level, plus hanzi → any of them
   end to end via `convert --system` and `convertToWadeGiles`. Checked against
-  417 rows of an outside syllabary in every system — 3,336 cells.
+  417 rows of an outside syllabary in every system, which is 3,336 cells.
 - **Reading ambiguous Wade-Giles.** `readWadeGilesLoosely` allows for the
   apostrophes and diacritics real texts drop, and `splitWadeGiles` puts back the
   hyphens they lose. Measured: 52.07% of written syllables lose their identity
@@ -97,7 +192,7 @@ decoder internals and the build pipeline.
   follows them.
 - **Orthography rules.** The 重叠 hyphen for AABB and repeated words, the 成语
   hyphen from a curated list of 117, 老王 → `Lǎo Wáng`, and GB/T 16159 5.1 in
-  full — 毛泽东 is `Máo Zédōng`, 北京大学 is `Běijīng Dàxué`, on boundaries
+  full, so 毛泽东 is `Máo Zédōng` and 北京大学 is `Běijīng Dàxué`, on boundaries
   CC-CEDICT's own capitalisation states.
 - **Typed rule overrides on the lattice** (`READING_RULES`), with the modal 得
   and attested 儿化 as the first two.
@@ -130,17 +225,17 @@ decoder internals and the build pipeline.
 
 ### Accuracy at 1.0.0
 
-Over the 105-case gold corpus, which is committed to the repository — not to
-the published package — and scored by `pnpm accuracy`:
+Over the 118-case gold corpus, which is committed to the repository rather than
+to the published package, and scored by `pnpm accuracy`:
 
 |                  |   lattice | greedy baseline |
 | ---------------- | --------: | --------------: |
-| exact match      | **97.1%** |           92.4% |
-| reading accuracy |     99.7% |           98.6% |
-| spacing (F1)     | **99.7%** |           97.0% |
+| exact match      | **97.5%** |           88.1% |
+| reading accuracy |     99.7% |           98.3% |
+| spacing (F1)     | **99.8%** |           96.3% |
 
 Every figure in that table is asserted against the scorer by
-`src/changelog.test.ts`, because a number nothing executes goes stale — which is
+`src/changelog.test.ts`, because a number nothing executes goes stale, which is
 what happened to this project's README table across three releases.
 
 `pnpm polyphones` reports 89.04% for the lattice against greedy's 88.82% over

package/README.md

@@ -70,7 +70,7 @@ A command given no arguments reads standard input, one text per line, so
 dictionary at all and start without loading one.
 
 At a terminal each syllable is written in its tone's colour, in
-[MDBG](https://www.mdbg.net)'s palette — red, yellow, green, blue, and the
+[MDBG](https://www.mdbg.net)'s palette of red, yellow, green, blue, and the
 terminal's own colour for the neutral tone. It is off for a pipe, `NO_COLOR` is
 honoured, `--colour` and `--no-colour` force it either way, and `--json` is
 never coloured. See [the command line](docs/cli/#colour).
@@ -85,9 +85,8 @@ $ pinyinjs convert 银行
 yínháng
 ```
 
-Everything else has columns for a person to read. Add `--json` — to any
-command — and it writes one JSON document per answer instead, which is what
-`jq` wants:
+Everything else has columns for a person to read. Add `--json` to any command
+and it writes one JSON document per answer instead, which is what `jq` wants:
 
 ```console
 $ pinyinjs explain 长江大桥 --json | jq -c '.syllables[] | select(.state != "locked")'
@@ -149,16 +148,16 @@ first, convert with it, and reload as `full` arrives.
 convert(dictionary, "银行"); // "yínháng"
 convert(dictionary, "行长"); // "hángzhǎng"
 convert(dictionary, "我要去北京。"); // "Wǒ yào qù Běijīng."
-convert(dictionary, "3D银行"); // "sān D yínháng" — the digit is read, the letter is not
+convert(dictionary, "3D银行"); // "sān D yínháng", the digit is read, the letter is not
 ```
 
 A reading the dictionary cannot settle on its own is settled by context, with
 typed rules over the lattice rather than tweaks to the output:
 
 ```ts
-convert(dictionary, "我得走了"); // "wǒ děi zǒule" — modal 得
-convert(dictionary, "他跑得很快"); // "tā pǎo de hěn kuài" — the particle
-convert(dictionary, "那边儿"); // "nà biānr" — 儿 does not stand on its own
+convert(dictionary, "我得走了"); // "wǒ děi zǒule", modal 得
+convert(dictionary, "他跑得很快"); // "tā pǎo de hěn kuài", the particle
+convert(dictionary, "那边儿"); // "nà biānr", 儿 does not stand on its own
 ```
 
 See [converting](docs/converting/#rules-where-the-cost-model-cannot-reach).
@@ -226,7 +225,7 @@ writes in a way no rule reaches.
 
 ```ts
 convert(dictionary, "他看了"); // "tā kànle"
-convert(dictionary, "我还给你了。"); // "Wǒ huán gěi nǐ le." — sentence-final 了
+convert(dictionary, "我还给你了。"); // "Wǒ huán gěi nǐ le.", sentence-final 了
 convert(dictionary, "作者"); // "zuòzhě"
 convert(dictionary, "南京市"); // "Nánjīng Shì"
 convert(dictionary, "南京市", { grouping: false }); // "Nánjīngshì"
@@ -246,7 +245,7 @@ a boundary inside it.
 ```ts
 convert(dictionary, "干干净净"); // "gāngān-jìngjìng"
 convert(dictionary, "研究研究"); // "yánjiū-yánjiū"
-convert(dictionary, "爸爸妈妈"); // "bàba māma" — that shape, but two words
+convert(dictionary, "爸爸妈妈"); // "bàba māma", that shape, but two words
 ```
 
 **A 成语 that can be read as two disyllables** takes the same hyphen, from a
@@ -254,7 +253,7 @@ curated list of 117; the rest are written solid, as the standard writes them.
 
 ```ts
 convert(dictionary, "风平浪静"); // "fēngpíng-làngjìng"
-convert(dictionary, "不亦乐乎"); // "búyìlèhū" — cannot be halved
+convert(dictionary, "不亦乐乎"); // "búyìlèhū", cannot be halved
 ```
 
 **Digits are read**, and the rest of a non-Han run passes through exactly as
@@ -266,7 +265,7 @@ convert(dictionary, "1988年之后"); // "yī jiǔ bā bā nián zhīhòu"
 convert(dictionary, "95%的人"); // "bǎifēnzhījiǔshíwǔ de rén"
 convert(dictionary, "3D打印"); // "sān D dǎyìn"
 convert(dictionary, "6:30起床"); // "liù diǎn sānshí fēn qǐchuáng"
-convert(dictionary, "16:9的"); // "16:9de" — a ratio is not a quantity
+convert(dictionary, "16:9的"); // "16:9de", a ratio is not a quantity
 ```
 
 `numbers: "keep"` leaves every digit alone. See [numbers](docs/numerals/).
@@ -282,13 +281,13 @@ import { convertPieces, isUncertain, writeSyllable } from "@kensio/pinyinjs";
 const pieces = convertPieces(dictionary, "银行");
 pieces.map((piece) => piece.text); // ["yín", "háng"]
 pieces[1]?.syllable; // { initial: "h", final: "ang", tone: 2 }
-pieces[0]?.confidence?.isLocked; // true — nothing else can be read here
+pieces[0]?.confidence?.isLocked; // true, nothing else can be read here
 pieces[1]?.confidence?.alternatives.map((found) =>
   found.reading.map((syllable) => writeSyllable(syllable)).join(""),
 ); // ["xíng", "héng", "hàng"]
 ```
 
-A piece with no `syllable` is the text between two of them — a space, or a run
+A piece with no `syllable` is the text between two of them: a space, or a run
 that was never Han. `joinPieces(pieces)` gives back exactly what `convert`
 returns.
 
@@ -306,8 +305,8 @@ const guesses = (text: string) =>
     (piece) => piece.confidence !== undefined && isUncertain(piece.confidence),
   );
 
-guesses("行").map((piece) => piece.text); // ["xíng"] — nothing but a prior chose it
-guesses("银行").map((piece) => piece.text); // [] — the word settles both syllables
+guesses("行").map((piece) => piece.text); // ["xíng"], nothing but a prior chose it
+guesses("银行").map((piece) => piece.text); // [], the word settles both syllables
 ```
 
 An alternative's `cost` says how much more the cheapest conversion taking it
@@ -327,7 +326,7 @@ convertToHtml(dictionary, "行");
 One element per syllable, with `py-tone-1` to `py-tone-5` (5 is the neutral
 tone), and `py-uncertain` plus the rejected readings where the decoder was
 guessing. Text that is not Han is escaped, not marked up. No styles are
-included — write your own:
+included, so write your own:
 
 ```css
 .py-tone-1 {
@@ -348,12 +347,12 @@ have.
 const entry = dictionary.lookup("头发");
 entry?.reading; // [{ initial: "t", final: "ou", tone: 2 }, { initial: "f", final: "a", tone: 5 }]
 entry?.isProperNoun; // false
-entry?.partOfSpeech; // "n" — jieba's tag
+entry?.partOfSpeech; // "n", jieba's tag
 
 dictionary.lookup("頭髮")?.reading; // the same reading, found under 繁體
 dictionary.lookup("重複")?.reading; // 重複 and 重覆 are both keys for 重复
-dictionary.hasPrefix("银"); // true — does any word start with this?
-dictionary.readingsOf("行"); // xíng, háng, héng, hàng — likeliest first
+dictionary.hasPrefix("银"); // true, does any word start with this?
+dictionary.readingsOf("行"); // xíng, háng, héng, hàng, likeliest first
 ```
 
 Both scripts are keys in the same dictionary, so nothing is converted before a
@@ -367,12 +366,12 @@ The syllable layer needs no dictionary and no network.
 import { isSyllable, readSyllable, writeSyllable } from "@kensio/pinyinjs";
 
 readSyllable("jiù"); // { initial: "j", final: "iou", tone: 4 }
-readSyllable("jiu4"); // the same — both notations parse
+readSyllable("jiu4"); // the same, both notations parse
 readSyllable("lv4"); // { initial: "l", final: "ü", tone: 4 }
 readSyllable("hello"); // undefined
-readSyllable("běi3"); // undefined — one notation at a time
+readSyllable("běi3"); // undefined, one notation at a time
 
-isSyllable("wánr"); // true — 儿化 is a suffix, not a syllable of its own
+isSyllable("wánr"); // true, 儿化 is a suffix, not a syllable of its own
 ```
 
 Initials and finals are the _underlying_ forms rather than the spelling, so 就 is
@@ -390,7 +389,7 @@ Input takes either notation, the `v` and `u:` conventions for ü, and raised ton
 digits. Output is standard diacritics unless asked otherwise.
 
 Parsing answers whether a spelling is _well formed_, not whether Mandarin uses
-it — `shong` parses and is not a real syllable. The attested inventory is
+it: `shong` parses and is not a real syllable. The attested inventory is
 separate:
 
 ```ts
@@ -410,7 +409,7 @@ splitSyllables("nǐhǎo"); // ["nǐ", "hǎo"]
 splitSyllables("Xī'ān"); // ["Xī", "ān"]
 splitSyllables("yinhang"); // ["yin", "hang"]
 splitSyllables("guórén"); // ["guó", "rén"], not ["guór", "én"]
-splitSyllables("hǎiōu"); // ["hǎi", "ōu"] — missing apostrophe, read anyway
+splitSyllables("hǎiōu"); // ["hǎi", "ōu"], missing apostrophe, read anyway
 readWord("yínháng"); // the same, parsed into Syllable objects
 ```
 
@@ -436,20 +435,21 @@ written at all.
 
 ## Numbers
 
-Reading a number needs no dictionary — arithmetic and about twenty readings —
-so this works with nothing loaded.
+Reading a number needs no dictionary, just arithmetic and about twenty
+readings, so this works with nothing loaded.
 
 ```ts
 import { numeralHanzi, percentHanzi, readNumeral } from "@kensio/pinyinjs";
 
 numeralHanzi(12345); // "一万两千三百四十五"
-numeralHanzi(1005); // "一千零五" — a skipped place is spoken
-numeralHanzi(2000); // "两千" — a leading lone 2 before a big unit
-percentHanzi(95); // "百分之九十五" — the order reverses
+numeralHanzi(1005); // "一千零五", a skipped place is spoken
+numeralHanzi(2000); // "两千", a leading lone 2 before a big unit
+numeralHanzi(2, { counts: true }); // "两", as in 两个西瓜, never 二个
+percentHanzi(95); // "百分之九十五", the order reverses
 ```
 
-The same digits are read two ways and nothing in the number says which — 2026年
-is spelled out and 2026个 is counted — so the style is the caller's:
+The same digits are read two ways and nothing in the number says which, since
+2026年 is spelled out and 2026个 is counted, so the style is the caller's:
 
 ```ts
 numeralHanzi(2026); // "两千零二十六"
@@ -484,7 +484,7 @@ writeIpa(jiu); // "tɕiou˥˩"
 ```
 
 Gwoyeu Romatzyh is the odd one, and it needs no tone mark because the tone is
-spelled into the syllable — which is why 陝西 is Shaanxi in English and 山西 is
+spelled into the syllable, which is why 陝西 is Shaanxi in English and 山西 is
 Shanxi:
 
 ```ts
@@ -496,7 +496,7 @@ Reading Wade-Giles back gives an **array**, because real text drops the
 apostrophes and diacritics that carry the distinctions:
 
 ```ts
-readWadeGilesLoosely("chi¹"); // [jī, qī] — chi is jī, ch'i is qī
+readWadeGilesLoosely("chi¹"); // [jī, qī]: chi is jī, ch'i is qī
 readWadeGilesLoosely("chu¹"); // [zhū, chū, jū, qū]
 ```
 
@@ -514,7 +514,7 @@ array, so it can be switched off and works across word boundaries.
 import { applySandhi, readWord } from "@kensio/pinyinjs";
 
 const buShi = readWord("bùshì") ?? [];
-applySandhi(buShi); // bú shì — 不 flattens before a fourth tone
+applySandhi(buShi); // bú shì, 不 flattens before a fourth tone
 applySandhi(buShi, { yiBu: false }); // unchanged
 
 const niHao = readWord("nǐhǎo") ?? [];