polytypo 1.20.1 → 1.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/lib/polytypo/data/VERSION +1 -1
  3. data/lib/polytypo/data/fixtures/bg.json +12 -1
  4. data/lib/polytypo/data/fixtures/cs.json +12 -1
  5. data/lib/polytypo/data/fixtures/de-CH.json +12 -1
  6. data/lib/polytypo/data/fixtures/de-DE.json +12 -1
  7. data/lib/polytypo/data/fixtures/el.json +12 -1
  8. data/lib/polytypo/data/fixtures/en-GB.json +12 -1
  9. data/lib/polytypo/data/fixtures/en-US.json +403 -1
  10. data/lib/polytypo/data/fixtures/es.json +12 -1
  11. data/lib/polytypo/data/fixtures/fi.json +12 -1
  12. data/lib/polytypo/data/fixtures/fr-CA.json +12 -1
  13. data/lib/polytypo/data/fixtures/fr.json +12 -1
  14. data/lib/polytypo/data/fixtures/hr.json +12 -1
  15. data/lib/polytypo/data/fixtures/hu.json +12 -1
  16. data/lib/polytypo/data/fixtures/it.json +12 -1
  17. data/lib/polytypo/data/fixtures/locale-resolution.json +1 -1
  18. data/lib/polytypo/data/fixtures/lt.json +12 -1
  19. data/lib/polytypo/data/fixtures/nl.json +12 -1
  20. data/lib/polytypo/data/fixtures/pl.json +12 -1
  21. data/lib/polytypo/data/fixtures/pt-BR.json +12 -1
  22. data/lib/polytypo/data/fixtures/pt-PT.json +12 -1
  23. data/lib/polytypo/data/fixtures/ro.json +12 -1
  24. data/lib/polytypo/data/fixtures/ru.json +12 -1
  25. data/lib/polytypo/data/fixtures/sk.json +12 -1
  26. data/lib/polytypo/data/fixtures/sl.json +12 -1
  27. data/lib/polytypo/data/fixtures/sr.json +12 -1
  28. data/lib/polytypo/data/fixtures/sv.json +12 -1
  29. data/lib/polytypo/data/fixtures/tr.json +12 -1
  30. data/lib/polytypo/data/fixtures/uk.json +12 -1
  31. data/lib/polytypo/data/locales/bg.json +1 -0
  32. data/lib/polytypo/data/locales/cs.json +1 -0
  33. data/lib/polytypo/data/locales/de-CH.json +6 -0
  34. data/lib/polytypo/data/locales/de-DE.json +7 -0
  35. data/lib/polytypo/data/locales/el.json +1 -0
  36. data/lib/polytypo/data/locales/en-GB.json +7 -0
  37. data/lib/polytypo/data/locales/en-US.json +7 -0
  38. data/lib/polytypo/data/locales/es.json +1 -0
  39. data/lib/polytypo/data/locales/fi.json +1 -0
  40. data/lib/polytypo/data/locales/fr-CA.json +1 -0
  41. data/lib/polytypo/data/locales/fr.json +1 -0
  42. data/lib/polytypo/data/locales/hr.json +1 -0
  43. data/lib/polytypo/data/locales/hu.json +1 -0
  44. data/lib/polytypo/data/locales/it.json +1 -0
  45. data/lib/polytypo/data/locales/lt.json +1 -0
  46. data/lib/polytypo/data/locales/nl.json +1 -0
  47. data/lib/polytypo/data/locales/pl.json +1 -0
  48. data/lib/polytypo/data/locales/pt-BR.json +1 -0
  49. data/lib/polytypo/data/locales/pt-PT.json +1 -0
  50. data/lib/polytypo/data/locales/registry.json +1 -1
  51. data/lib/polytypo/data/locales/ro.json +1 -0
  52. data/lib/polytypo/data/locales/ru.json +1 -0
  53. data/lib/polytypo/data/locales/sk.json +1 -0
  54. data/lib/polytypo/data/locales/sl.json +1 -0
  55. data/lib/polytypo/data/locales/sr.json +1 -0
  56. data/lib/polytypo/data/locales/sv.json +1 -0
  57. data/lib/polytypo/data/locales/tr.json +1 -0
  58. data/lib/polytypo/data/locales/uk.json +1 -0
  59. data/lib/polytypo/data/rules/order.json +9 -1
  60. data/lib/polytypo/data/rules/pipeline-idempotency.md +23 -3
  61. data/lib/polytypo/data/rules/quote-punctuation.md +334 -0
  62. data/lib/polytypo/data/rules/quotes.md +9 -0
  63. data/lib/polytypo/data/schema/fixtures.schema.json +1 -0
  64. data/lib/polytypo/data/schema/locale.schema.json +12 -1
  65. data/lib/polytypo/engine/locale.rb +22 -1
  66. data/lib/polytypo/engine/pipeline.rb +1 -1
  67. data/lib/polytypo/engine/rules/quote_punctuation.rb +79 -0
  68. data/lib/polytypo/engine/rules.rb +1 -0
  69. data/lib/polytypo/version.rb +1 -1
  70. metadata +3 -1
@@ -12,6 +12,7 @@
12
12
  "close": "’",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "«",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "’",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": ["d", "n", "pel", "m", "t", "lh", "sant"],
@@ -12,6 +12,7 @@
12
12
  "close": "”",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": ["d", "n", "pel", "m", "t", "lh", "sant"],
@@ -1,5 +1,5 @@
1
1
  {
2
- "spec": "1.20.1",
2
+ "spec": "1.21.0",
3
3
  "$comment": "Locale resolution input. Algorithm is specified in spec/rules/locale-resolution.md and is identical in every runtime — never delegate it to a platform locale-negotiation library. \"spec\" here must track spec/VERSION exactly — it is not itself the global version source; scripts/validate-spec.mjs enforces the match.",
4
4
  "locales": [
5
5
  "en-US",
@@ -12,6 +12,7 @@
12
12
  "close": "»",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "“",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "‘",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "‹",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "’",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "’",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "’",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -12,6 +12,7 @@
12
12
  "close": "”",
13
13
  "innerSpace": "none"
14
14
  },
15
+ "punctuationPlacement": "none",
15
16
  "elisionIdioms": [],
16
17
  "elisionClitics": {
17
18
  "before": [],
@@ -1,5 +1,5 @@
1
1
  {
2
- "spec": "1.20.1",
2
+ "spec": "1.21.0",
3
3
  "$comment": "Single source of truth for pipeline order. Rules run in ascending `order`. Disabling a rule removes it from the sequence and never reorders the rest. Rule ids are public API (see docs/ARCHITECTURE.md section 5). \"spec\" here must track spec/VERSION exactly — it is not itself the global version source; scripts/validate-spec.mjs enforces the match.",
4
4
  "rules": [
5
5
  {
@@ -50,6 +50,14 @@
50
50
  "localeData": ["quotes"],
51
51
  "summary": "Straight quotes to locale primary/secondary pairs with nesting resolution. Runs before `apostrophe` so that a straight apostrophe is still available as quote evidence. Declines to pair a medial single-quoted `n` (spec 1.1.0, every locale) or a span matching a cited `quotes.elisionIdioms` entry, so that `apostrophe` converts both marks instead, and declines a mark written flush against an inline span boundary whose attaching word fragment is a cited `quotes.elisionClitics` entry (spec 1.4.0), so that a possessive or elision cannot take the pairing from the author's own quotation mark."
52
52
  },
53
+ {
54
+ "id": "quote-punctuation",
55
+ "order": 45,
56
+ "default": "off",
57
+ "modes": ["text", "html", "markdown", "yaml"],
58
+ "localeData": ["quotes"],
59
+ "summary": "Moves a comma or full stop from after a closing primary quotation mark to before it, for a locale whose cited convention puts them inside (quotes.punctuationPlacement = \"inside\"; en-US). Explicit opt-in (spec 1.21.0): it relocates a character the author typed, and in technical text a quoted literal then absorbs the punctuation (`set it to \"strict\".`). Declines after a digit, after another terminal, when anything but a space or the end of the text follows, and across any span boundary, so it never has to decide whether the punctuation belongs to the quotation. Off by default; enable with `{ rules: { \"quote-punctuation\": true } }`."
60
+ },
53
61
  {
54
62
  "id": "apostrophe",
55
63
  "order": 50,
@@ -36,6 +36,7 @@ Write the pipeline as `T = R₈ ∘ R₇ ∘ … ∘ R₂ₐ ∘ R₂ ∘ R₁`,
36
36
  | R₃ | `dashes` | 30 |
37
37
  | R₄ | `hyphen` | 35 |
38
38
  | R₅ | `quotes` | 40 |
39
+ | R₅ₐ | `quote-punctuation` | 45 |
39
40
  | R₆ | `apostrophe` | 50 |
40
41
  | R₇ | `symbols` | 60 |
41
42
  | R₈ | `nbsp` | 70 |
@@ -47,9 +48,16 @@ below holds for any subset, in the same relative order.)
47
48
  subscripts in this document had been cited by name from eight other rule documents. Renumbering
48
49
  `R₃ … R₈` to make the sequence contiguous would rewrite every one of those references for no
49
50
  gain in meaning, so the rule takes the letter and the composition `T = R₈ ∘ R₇ ∘ … ∘ R₂ₐ ∘ … ∘ R₁`
50
- reads with it in place at order 25. `ranges` is also the one rule that is **off by default**, so
51
- for most callers the sequence is literally the eight numbered ones; every proof below is stated
52
- over "the rules that run", which is the subset the caller's `rules` option selected.
51
+ reads with it in place at order 25. `ranges` is also one of the two rules that are **off by
52
+ default** (the other is `quote-punctuation`, below), so for most callers the sequence is literally
53
+ the eight numbered ones; every proof below is stated over "the rules that run", which is the
54
+ subset the caller's `rules` option selected.
55
+
56
+ **Why `quote-punctuation` is `R₅ₐ`.** Same reason as `ranges`: it arrived in spec 1.21.0 between
57
+ two rules whose subscripts are cited by name from other documents. It is the second rule that is
58
+ **off by default**, so with both off the sequence is the eight numbered rules; every proof below
59
+ is stated over the rules that run. When it does run, `I₅` must also survive it (§3, `I₅ₐ`), and `quote-punctuation.md`
60
+ §5 carries its obligation against `I₁ … I₅`.
53
61
 
54
62
  For each rule define the predicate
55
63
 
@@ -221,6 +229,18 @@ deletes only `(`…`)` spans; `quotes` (0.3.0) deletes only a run whose landing
221
229
  inside a word — `hyphen`'s `WORDISH = ALNUM ∪ HYPHENISH` excludes both a U+0020 and a quote
222
230
  glyph, so the deletion never lands inside a listed form (`quotes.md` 5). `I₄` is preserved.
223
231
 
232
+ ### I₅ₐ — `quote-punctuation`
233
+
234
+ `I₅ₐ(y)` requires that no pair `cp[i], cp[i+1]` in `y` satisfies `quote-punctuation.md` §3.2's
235
+ C1-C4: a primary close preceded by a letter, followed by a comma or full stop, followed by a
236
+ space-like code point or the end. It is vacuous for a locale whose
237
+ `quotes.punctuationPlacement` is `"none"`, and for every call that does not enable the rule.
238
+
239
+ **Who can violate it.** `apostrophe`, `symbols` and `nbsp`, by changing the class of `cp[i-1]` or
240
+ `cp[i+2]` or by putting a punctuation mark next to a primary close. The argument is in
241
+ `quote-punctuation.md` §5: none of them emits the primary close (QP-1), a letter or a
242
+ comma or full stop next to it, or anything that is not `SPACELIKE` where a space stood.
243
+
224
244
  ### I₅ … I₈
225
245
 
226
246
  `quotes`, `apostrophe`, `symbols` and `nbsp` are the last four rules; only `nbsp` has anything
@@ -0,0 +1,334 @@
1
+ # Rule: `quote-punctuation`
2
+
3
+ **Order:** 45. **Default:** off. **Modes:** text, html, markdown, yaml.
4
+ **Spec version:** 1.21.0 (new rule).
5
+
6
+ ---
7
+
8
+ ## 1. Purpose
9
+
10
+ `quote-punctuation` moves a comma or a full stop from after a closing primary quotation mark to
11
+ before it, for a locale whose cited convention puts them inside the mark. It exists because
12
+ `quotes` converts glyphs and nothing else: `"hello",` becomes `“hello”,` in `en-US` and
13
+ `‘hello’,` in `en-GB`, and in both the comma stays where the author put it (canonical
14
+ polytypo#74). For American English that is the wrong place — Chicago sets commas and periods
15
+ before the closing mark (the citation is in `spec/locales/en-US.json`) — so text typeset by
16
+ `en-US` still carries British placement whenever its author typed it.
17
+
18
+ Every other rule in this project changes characters while keeping each one next to the neighbours
19
+ the author gave it. This rule changes where a character _sits_. That is why it is **off by
20
+ default** and why it is built to decline rather than to decide.
21
+
22
+ **What it deliberately does not do.** Where punctuation goes relative to a closing mark is, in
23
+ most locales, a question of meaning: a mark that belongs to the quoted material goes inside, one
24
+ that belongs to the surrounding sentence goes outside. `"Stop."` and `"most popular",` look alike
25
+ on the surface, and a scan of code points cannot tell them apart. So the rule is defined only
26
+ where the convention is positional — **a comma or a full stop goes inside, whatever the sense** —
27
+ and everywhere else (`en-GB`, German, and every locale whose placement was not verified) the
28
+ locale says `"none"` and the rule does nothing. The accepted cost of the one positional locale is
29
+ in §6.
30
+
31
+ ---
32
+
33
+ ## 2. Locale data consumed
34
+
35
+ - `quotes.punctuationPlacement` — one of `"inside"`, `"none"`. Required in every locale file.
36
+ `"none"` means the rule does nothing: either the locale places these marks by meaning, or no
37
+ convention has been verified (a missing citation is never a licence to guess). `"inside"` means
38
+ the locale's cited convention puts a comma or full stop before the closing primary mark.
39
+ - `quotes.primary.close` — the glyph the scan keys on. `quotes.secondary` is **not** read: a
40
+ secondary close is a `NARROW` glyph, and in `en-US` it is U+2019, which is also the apostrophe
41
+ (`the dogs’, bowls`).
42
+ - Nothing else. The rule has no tables of its own.
43
+
44
+ `"inside"` is a claim the algorithm's composition argument (§5) depends on, so
45
+ `scripts/validate-spec.mjs` refuses a locale file that makes it where that argument does not hold:
46
+
47
+ - **QP-1.** `quotes.primary.close` is a `WIDE` glyph (`quotes.md` §3.1) and differs from
48
+ `quotes.primary.open`. A symmetric pair cannot tell a closing mark from an opening one, and a
49
+ `NARROW` close is either the apostrophe glyph or a mark a word can end in.
50
+ - **QP-2.** `dash.parenthetical` is not `"em-paired"`. `dashes.md` §3.4a ends a segment at a
51
+ full stop that is followed by a space; moving the stop across the quotation mark removes that
52
+ boundary (`”.␣` becomes `.”␣`), so a pair of strokes the first pass kept apart could meet on the
53
+ second.
54
+ - **QP-3.** Neither `quotes.primary.innerSpace` nor `quotes.secondary.innerSpace` is a space. A
55
+ spaced primary pair puts a space on the mark's left, so the scan could never fire, and any
56
+ spaced pair keeps `quotes.md`'s `gapInsertable` non-vacuous, which §5's argument against `I₅`
57
+ relies on being vacuous.
58
+
59
+ `en-US` is the only locale that declares `"inside"` as of spec 1.21.0. The value is a statement
60
+ about a source, not about a language: `en-GB` and `de-DE` are `"none"` for the reason §1 gives,
61
+ and carry the citation that shows it; `de-CH` and every other `"none"` locale are `"none"` because
62
+ no convention has been verified for them.
63
+
64
+ ---
65
+
66
+ ## 3. Algorithm
67
+
68
+ Input is a code-point array `cp[0 … n-1]` in which modes may have placed boundary markers
69
+ (`modes.md` §3.2). The rule performs one left-to-right scan and produces edits; the pipeline
70
+ applies them. The rule is a no-op unless `quotes.punctuationPlacement` is `"inside"`.
71
+
72
+ ### 3.1 Character classes
73
+
74
+ The classes are those of `quotes.md` §3.1, unchanged: `LETTER`, `SPACELIKE` (which contains
75
+ `BREAK`, so a −2 line marker is `SPACELIKE`), and `NONE` for an index outside the array. The −1
76
+ inline marker is in none of them (`modes.md` §3.3). Let `Q` be `quotes.primary.close`.
77
+
78
+ ### 3.2 The scan
79
+
80
+ For each index `i` from `0` while `i + 1 < n`, in ascending order, the pair `cp[i], cp[i+1]` is
81
+ an **edit** if and only if all of the following hold:
82
+
83
+ | # | Condition |
84
+ | --- | -------------------------------------------------------------------------------- |
85
+ | C1 | `cp[i] = Q` |
86
+ | C2 | `cp[i+1]` is U+002C or U+002E |
87
+ | C3 | `i ≥ 1` and `cp[i-1]` is in `LETTER` |
88
+ | C4 | `cp[i+2]` is `NONE` or in `SPACELIKE` |
89
+
90
+ The edit replaces the two code points with `cp[i+1], cp[i]` — the same two code points in the
91
+ opposite order. After an edit continue from `i + 2`; otherwise from `i + 1`.
92
+
93
+ **What each condition buys.**
94
+
95
+ - **C3** requires a letter, not merely a non-space. It declines after a digit (`5”,` is the shape
96
+ of an inch mark and of a quoted number), after another terminal (`”!.`, `…”.`), after a
97
+ full stop (`e.g.”,` — whether the stop belongs to the abbreviation is not decidable here), after
98
+ any quotation mark (a nested quotation, `“He said ‘hi’”.`), after a bracket, and across any
99
+ boundary marker or protected run (the marker is not `LETTER`).
100
+ - **C4** requires the punctuation to end its clause. It declines when a letter, a digit, a
101
+ bracket, another dot, a quotation mark or a boundary marker comes next: `“file”.txt`,
102
+ `(“hi”.)`, `“wait”…`, and `“file”.${ext}` with a protected `${ext}`.
103
+ - **C2** moves only the comma and the full stop. `;` `:` `?` `!` and the dashes are positional in
104
+ no locale this specification has verified — Chicago puts them outside unless they belong to the
105
+ quotation — so they are left where the author wrote them, and so is a full stop that duplicates
106
+ a terminal already inside the mark (`“Stop!”.`, which stays).
107
+
108
+ The edit has length two for length two, so it never changes the length of the text, never
109
+ inserts a U+0020, and never needs the edge-growth check of `modes.md` §3.4: the replacement's
110
+ first and last code points are not U+0020.
111
+
112
+ ### 3.3 Modes, `protect`, `analyze`
113
+
114
+ **Document modes.** A span boundary between the mark and the punctuation, or on either side of
115
+ the pair, puts a marker at `cp[i-1]`, `cp[i+1]` or `cp[i+2]`. A marker at `cp[i-1]` fails C3, at
116
+ `cp[i+1]` fails C2, and at `cp[i+2]` fails C4. The rule therefore needs no special handling of
117
+ `html`, `markdown` or `yaml`: it acts only when the whole of `Q`, the punctuation, and the text on
118
+ either side are in one span, and the redistribution of edits to spans is trivial because the edit
119
+ never contains a marker. The end of a text unit is `NONE`, not a marker, so `<p>Call it
120
+ "ready".</p>` moves the stop while `<p>Call it "ready".</p><p>Next</p>` does not (§6).
121
+
122
+ **`text` mode `protect`.** A protected run is a boundary marker, including at the very start or
123
+ end of the input (`modes.md` §3.9.3), so it blocks the scan the same way. The edit never changes
124
+ the length of the text and never touches a protected code point, so a case's `protectOut` equals
125
+ its `protect`.
126
+
127
+ **`analyze`.** Reports one change per edit, with `ruleId` `quote-punctuation`, and only when the
128
+ rule is enabled for the call (`analyze.md` A4).
129
+
130
+ ---
131
+
132
+ ## 4. Must not touch
133
+
134
+ **Scope.** Per [pipeline-idempotency.md](pipeline-idempotency.md) §5.2 each bullet is **[P]** — a
135
+ guarantee of `transform` as a whole — or **[R]** — true of this rule in isolation but capable of
136
+ being falsified by another rule, which is then named.
137
+
138
+ - **[P] Anything, unless the caller asked.** The rule is off by default; `transform` without
139
+ `{ rules: { "quote-punctuation": true } }` leaves every comma and stop where it was typed.
140
+ - **[P] Every locale whose `punctuationPlacement` is `"none"`.** Enabling the rule is a no-op
141
+ there.
142
+ - **[P] `;` `:` `?` `!`** and a full stop that follows one: `“Stop!”.` is unchanged.
143
+ - **[P] A punctuation mark after a digit or a non-letter.** `“Route 66”.`, `6’ 2”,`.
144
+ - **[P] A nested quotation's closing mark.** `“He said ‘hi’”.` — the glyph left of the primary
145
+ close is `’`, not a letter.
146
+ - **[P] A secondary close, and the apostrophe.** `the dogs’, bowls`. The scan keys on the primary
147
+ close only (QP-1).
148
+ - **[P] A stop or comma followed by anything but a space, a line break or the end of the text.**
149
+ `“file”.txt`, `(“hi”.)`, `“wait”…`, `“a”,”b”`.
150
+ - **[P] Across a span boundary or a protected run, on any of the three sides.**
151
+ - **[P] A straight quotation mark.** The rule reads the glyph `quotes` produced; an unconverted
152
+ U+0022 is not `Q`.
153
+ - **[R] Which marks are quotation marks.** Decided by `quotes`; this rule moves a punctuation mark
154
+ next to one that `quotes` already settled, or that the author already typed in curly form.
155
+
156
+ ---
157
+
158
+ ## 5. Idempotency argument
159
+
160
+ **The rule alone.** An edit swaps `Q` and a punctuation mark. Afterwards `Q` stands at `i+1`
161
+ with `cp[i+2]` unchanged, and `cp[i+2]` is `NONE` or `SPACELIKE`, which is not U+002C or U+002E, so
162
+ C2 fails there. The punctuation mark now at `i` is not `Q`, so C1 fails there. A candidate pair
163
+ elsewhere reads `cp[j-1]`, `cp[j]`, `cp[j+1]` and `cp[j+2]`; an edit at `i` changes only `cp[i]`
164
+ and `cp[i+1]`. For `j > i + 1` to read either, `j - 1 ≤ i + 1`, so `j ≤ i + 2`; but `j = i + 2`
165
+ requires `cp[i+2] = Q`, which C4 excludes. For `j < i`, `j + 2 ≥ i` means `j = i - 2` and
166
+ `cp[j+2] = cp[i]`, which was `Q` and is not `NONE` or `SPACELIKE`, so `j` was not a candidate
167
+ before and is not one after. Two candidates are never adjacent for the same reason. Hence
168
+ `T(T(x)) = T(x)` for this rule on its own, and `I₅ₐ(y)` — "no pair in `y` satisfies C1–C4" — holds
169
+ on its output.
170
+
171
+ ### Composition obligation
172
+
173
+ Per [pipeline-idempotency.md](pipeline-idempotency.md) §5. This rule is **R₅ₐ**; it runs after
174
+ `quotes` (R₅) and before `apostrophe` (R₆), so the obligation runs against `spaces`, `ellipsis`,
175
+ `ranges`, `dashes`, `hyphen` and `quotes` (its output must satisfy their invariants), and `I₅ₐ`
176
+ must survive `apostrophe`, `symbols` and `nbsp`.
177
+
178
+ **What this rule emits.** The same two code points it consumed, swapped: `Q` moves right by one
179
+ index and U+002C or U+002E moves left by one. **No code point is inserted or deleted**, and the
180
+ neighbours of the pair are `cp[i-1] ∈ LETTER` on the left and `NONE` or `SPACELIKE` on the right,
181
+ both before and after the edit.
182
+
183
+ - **`I₁` (`spaces`).** Discharged. No U+0020 is created and none is removed. A U+0020 before the
184
+ punctuation is impossible (`cp[i-1]` is a letter before the edit, and after it the punctuation's
185
+ left neighbour is that same letter). `spaces` removes a run of U+0020 when the code point to
186
+ its right is in `STRIP-BEFORE`; no run ends at `cp[i]` or `cp[i+1]` either before or after the
187
+ edit, because `cp[i-1]` is a letter and the swapped pair is adjacent.
188
+ - **`I₂` (`ellipsis`).** Discharged. A single dot is moved; C4 excludes a following dot and C3
189
+ excludes a preceding one (`…”.` and `”...` are both declined), so no run of dots is formed or
190
+ split.
191
+ - **`I₂ₐ` (`ranges`), `I₃` (`dashes`).** Discharged by class membership: `Q`, U+002C and U+002E
192
+ are in none of `DASH`, `INERT-DASH`, `DIGIT`, `SPACE`, `NOBREAK-SPACE`, `JOINER` or `ROMAN`, so
193
+ a token's `cp[L]`, `cp[R]`, `before`, `after` and cluster never move between classes. The one
194
+ place `dashes` reads a full stop is §3.4a's segment boundary, excluded by **QP-2**.
195
+ - **`I₄` (`hyphen`).** Discharged. A listed form is bounded by `¬WORDISH` on both sides; `Q`, `,`
196
+ and `.` are all outside `WORDISH`, so the boundary does not move.
197
+ - **`I₅` (`quotes`).** Discharged by comparing the verdict inputs `quotes` reads at the mark.
198
+ For the mark itself: `Lskip` changes from a letter (`ALNUM`) to the punctuation mark (neither
199
+ `NONE` nor `SPACELIKE`) and `closeRight` from the punctuation mark (`CLOSEISH`) to `NONE` or
200
+ `SPACELIKE`; `canClose` accepts both before and after, and `canOpen` rejects both (`openLeft` is
201
+ a letter before, and `,` or `.` — in `CLOSEISH` but not `OPENISH` — after). For a candidate to
202
+ the right, across the spaces: `Lskip` changes from the punctuation mark to `Q`, and
203
+ `canClose`/`canOpen` read it only against `NONE` and `SPACELIKE`. The elision vetoes read
204
+ `NARROW` marks and `ALNUM` neighbours, and none of the code points that moved is either. The
205
+ gap test `gapInsertable` is vacuous because **QP-3** forbids a spaced pair. So the candidates,
206
+ their verdicts and their pairing are the same on the second pass, and the certification gate
207
+ (`quotes.md` §3.5) sees the same document modulo this swap.
208
+ - **`I₅ₐ` against `apostrophe` (R₆).** Discharged. `apostrophe` emits only U+2019, never `Q`
209
+ (QP-1 excludes a `Q` equal to U+2019), so it creates no candidate; and it changes a code point
210
+ to U+2019 only where it stood as U+0027, which is not `LETTER`, so it cannot make `cp[i-1]` a
211
+ letter.
212
+ - **`I₅ₐ` against `symbols` (R₇).** Discharged. `symbols` emits U+00A9, U+00AE, U+2122, U+00D7
213
+ and U+00B1, none in `LETTER` or `SPACELIKE`, and replaces spans bounded by non-`ALNUM`
214
+ neighbours, so it cannot make `cp[i-1]` a letter or `cp[i+2]` a space.
215
+ - **`I₅ₐ` against `nbsp` (R₈).** Discharged. `nbsp` converts one space to another or inserts a
216
+ space; `SPACELIKE` accepts either, so C4 holds both ways. `nbsp` can insert a space between
217
+ `Q` and the punctuation (N1/N2) only if the locale lists that punctuation in
218
+ `beforePunctuation` or `narrowBeforePunctuation`, which `en-US` does not; if a locale did, the
219
+ insertion would make `cp[i+1]` a space, which fails C2, so the pair is no longer a candidate.
220
+
221
+ **What is argued and what is measured.** The discharges against `ellipsis`, `ranges`, `dashes`,
222
+ `hyphen` and `nbsp` are class-membership arguments over the alphabet `{Q, U+002C, U+002E}` and
223
+ the two neighbour classes, in the shape of `symbols.md` §5, not CO-S proofs, and each runtime's
224
+ idempotency sweep with the rule enabled is the control (`pipeline-idempotency.md` §5.1a). A
225
+ throwaway reference implementation of §3.2 (not a runtime) was applied to the **finished output** of
226
+ the `polytypo` 1.20.1 pipeline — that is, after `apostrophe`, `symbols` and `nbsp` had run, not
227
+ between `quotes` and `apostrophe` where the rule sits — over the released `en-US` text fixtures,
228
+ 1,128 variants of them with a comma or stop added after each quotation mark, and 400,000 random
229
+ strings of letters, quotation marks, commas, stops, spaces, brackets and dashes. For each, the
230
+ scanned output was re-run through the pipeline and the scan, and came back unchanged. No violation
231
+ was found. That checks that the pipeline leaves a scanned text alone; it does **not** check the
232
+ rule's composition against `apostrophe`, `symbols` or `nbsp` in its real position, and it is no
233
+ proof. Those checks belong to the runtimes' own sweeps.
234
+
235
+ ---
236
+
237
+ ## 6. Worked examples
238
+
239
+ `⟶` = no change. Every row is a conformance fixture in `spec/fixtures/en-US.json` with
240
+ `rules: { "quote-punctuation": true }`, unless it says otherwise. Input is the author's text; the
241
+ output is what the whole pipeline produces, so a row shows `quotes`' conversion and this rule's
242
+ move together.
243
+
244
+ ### `en-US` — `punctuationPlacement: "inside"`, text mode
245
+
246
+ | # | Input | Output | Why |
247
+ | --- | ----------------------------------- | ----------------------------------- | --------------------------------------------------------- |
248
+ | 1 | `She said "hello", then left.` | `She said “hello,” then left.` | C1–C4 |
249
+ | 2 | `He called it "done". Then he left.`| `He called it “done.” Then he left.`| a stop, followed by a space |
250
+ | 3 | `Call it "ready".` | `Call it “ready.”` | C4: end of the text is `NONE` |
251
+ | 4 | `Call it "ready".` + U+000A + `Next`| `Call it “ready.”` + U+000A + `Next`| C4: a line break is `SPACELIKE` |
252
+ | 5 | `The "first", the "second".` | `The “first,” the “second.”` | two independent edits |
253
+ | 6 | `"Go home".` | `“Go home.”` | **a complete sentence in the quotation is not special** |
254
+ | 7 | `Both "a", "b" and "c".` | `Both “a,” “b” and “c.”` | the middle quotation has nothing to move |
255
+ | 8 | `She said “hello,” then left.` | ⟶ | already inside: nothing at `cp[i+1]` |
256
+ | 9 | `Broken pair”, then` | `Broken pair,” then` | **an unpaired closing mark is moved too** (accepted cost) |
257
+ | 10 | `"Stop!".` | `“Stop!”.` | C3: the glyph on the left is `!` |
258
+ | 11 | `It said "wait…".` | `It said “wait…”.` | C3: `…` |
259
+ | 12 | `Use "e.g.", then` | `Use “e.g.”, then` | C3: `.` |
260
+ | 13 | `"Route 66".` | `“Route 66”.` | C3: a digit |
261
+ | 14 | `"He said 'hi'".` | `“He said ‘hi’”.` | C3: `’`; nested quotation, accepted miss |
262
+ | 15 | `Say "a"; say "b": say "c"?` | `Say “a”; say “b”: say “c”?` | C2: `;` `:` `?` are never moved |
263
+ | 16 | `"file".txt` | `“file”.txt` | C4: a letter follows |
264
+ | 17 | `He said ("hi".)` | `He said (“hi”.)` | C4: a bracket follows |
265
+ | 18 | `He said "wait"...` | `He said “wait”…` | `ellipsis` runs first; C2 fails on U+2026 |
266
+ | 19 | `Check the dogs’, bowls and cats.` | ⟶ | U+2019 is the secondary close, not `Q` (QP-1) |
267
+ | 20 | `She said "hello", then left.`, rule not enabled | `She said “hello”, then left.` | the default: off |
268
+
269
+ ### Document modes and `protect`
270
+
271
+ | # | Mode | Input | Output | Why |
272
+ | --- | ---------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
273
+ | H1 | `html` | `<p>She said "hello", then left.</p>` | `<p>She said “hello,” then left.</p>` | one text node |
274
+ | H2 | `html` | `<p>She said <em>"hello"</em>, then left.</p>` | `<p>She said <em>“hello”</em>, then left.</p>` | a marker at `cp[i+1]` fails C2 |
275
+ | H3 | `html` | `<p>She said "<em>hello</em>", then left.</p>` | `<p>She said “<em>hello</em>”, then left.</p>` | a marker at `cp[i-1]` fails C3 |
276
+ | H5 | `html` | `<p>She said "hello".</p><p>Next.</p>` | `<p>She said “hello”.</p><p>Next.</p>` | the gap between the paragraphs is a −1 marker at `cp[i+2]`: C4 fails |
277
+ | M1 | `markdown` | `She said "hello", then left.` + U+000A | `She said “hello,” then left.` + U+000A | one span |
278
+ | M2 | `markdown` | `*She said "hello"*, then left.` | `*She said “hello”*, then left.` | the closing `*` is a boundary |
279
+ | M3 | `markdown` | `*He said "hi".* Next` | `*He said “hi”.* Next` | the same, at `cp[i+2]` |
280
+ | Y1 | `yaml` | `title: She said "hello", then left.` | `title: She said “hello,” then left.` | a processable plain scalar is one span |
281
+ | P1 | `text`, `protect` | `Set "file".${ext} now` | `Set “file”.${ext} now` | the protected run is a marker at `cp[i+2]` |
282
+ | P2 | `text`, `protect` | `Use "${name}", then stop.` | `Use “${name}”, then stop.` | the protected run is a marker at `cp[i-1]` |
283
+ | P3 | `text`, `protect` | `Say "hi", then ${x}.` | `Say “hi,” then ${x}.` | the hole is elsewhere; `protectOut` equals `protect` |
284
+
285
+ Rows P1 to P3 give `protect` as the code-point ranges of `${ext}`, `${name}` and `${x}`.
286
+
287
+ ### Every other locale
288
+
289
+ For each of the other twenty-six locales a fixture enables the rule on text that is already in
290
+ that locale's quotation marks, with a comma after the closing mark, and expects it back unchanged;
291
+ `en-GB` is the one that starts from straight quotes (`She said "hello", then left.` becomes
292
+ `She said ‘hello’, then left.`). They prove `"none"` is a no-op in every locale and keep the
293
+ rule from silently becoming locale-dependent.
294
+
295
+ ### Accepted costs
296
+
297
+ These are the price of declining rather than deciding, named so a reader can weigh them:
298
+
299
+ - **A quoted literal absorbs the punctuation.** `set it to "strict".` becomes `set it to
300
+ “strict.”`. In `en-US` that is the rule Chicago states for prose; for a literal it is wrong,
301
+ and the manual makes an exception (CMOS Shop Talk, “Section 7.75 in the Spotlight”, a
302
+ 16th-edition text; whether it holds in the 18th was not checked) that this rule does not model.
303
+ Code spans are skipped by every mode, so a literal in code is safe. This is also why the rule
304
+ is off by default: with it on, 4 of the 201 `en-US` fixtures that are in text mode, have an
305
+ `out`, and set no `rules` override (counted before this rule's own cases were added) would
306
+ produce different output.
307
+ - **No duplicate removal.** `“Stop!”.` keeps both marks.
308
+ - **Nested and numeric quotations are missed** (rows 13 and 14): `“Route 66”.` and
309
+ `“He said ‘hi’”.` keep the stop outside.
310
+ - **A closing tag or an emphasis delimiter right after the stop blocks the move** (H5, M3), while
311
+ the same text at the very end of a document moves it. A markup boundary is not a space.
312
+ - **An unpaired curly closing mark moves its punctuation** (row 9). The rule trusts the glyph,
313
+ not the pairing.
314
+ - **Every locale but `en-US` is untouched.** For `en-GB` and `de-DE` the cited placement depends
315
+ on meaning (University of Oxford Style Guide (2014): “place any punctuation which does not
316
+ belong to the quote outside”; Rat für deutsche Rechtschreibung 2024 §79 E1); for the others no
317
+ convention has been verified. A caller who wants it applied there has no option to ask for it.
318
+
319
+ ---
320
+
321
+ ## 7. Open questions
322
+
323
+ 1. **`"outside"`.** German places a comma after the closing mark when a carrier sentence
324
+ follows the quotation (§79 E1(2)); that is the one position-only statement found. A
325
+ value that moved a comma from inside to outside would be positional there and could be added to
326
+ the enum without changing any existing value. Nothing is specified for it; recorded because it
327
+ is the one other position-only convention the sources established.
328
+ 2. **Is a Chicago exception for computer terms a hole in `"inside"`?** CMOS Shop Talk, 2015, 16th
329
+ ed.: punctuation that is not part of a quoted computer term stays outside. The 18th edition
330
+ was not read. If it keeps the exception, a locale entry cannot express it and the rule's
331
+ default-off status is the only protection.
332
+ 3. **The primary close only.** A single-quoted first-level quotation (`en-GB`) is not covered by
333
+ QP-1 because `en-GB` is `"none"`; if a locale ever declares `"inside"` with a `NARROW` primary
334
+ close, QP-1 has to be revisited together with the apostrophe argument.
@@ -1271,6 +1271,15 @@ still holds without re-verification.
1271
1271
  *sites* rather than its emission alphabet alone — the alphabet by itself is not enough, because
1272
1272
  a `SPACELIKE` insertion is *not* inert at an arbitrary position; it is inert at exactly the
1273
1273
  positions `nbsp` can reach).
1274
+ - **`I₅` against `quote-punctuation` (R₅ₐ), spec 1.21.0, when enabled.** The rule swaps a primary
1275
+ close with a comma or full stop that follows it. The verdict inputs this rule reads at the mark
1276
+ move only within classes it tests identically (`Lskip`: `ALNUM` → `,`/`.`, neither `NONE` nor
1277
+ `SPACELIKE`; `closeRight`: `,`/`.` → `NONE` or `SPACELIKE`, both accepted by `canClose`;
1278
+ `openLeft`: a letter → `,`/`.`, neither `OPENISH`), the vetoes read `NARROW` marks and `ALNUM`
1279
+ neighbours that the swap does not touch, and `gapInsertable` is vacuous because the locale
1280
+ constraint QP-3 forbids a spaced pair wherever the rule is enabled
1281
+ (`quote-punctuation.md` §2, §5). A case analysis, not CO-S; the runtimes' idempotency sweeps
1282
+ with the rule on are the control.
1274
1283
  - **`I₅` against `symbols` (R₇).** **Known-weak: a case analysis, not CO-S.** `symbols`
1275
1284
  collapses `(c)`/`(r)`/`(tm)` to a single sign, deleting code points, and converts `x` to `×`
1276
1285
  between numerals. A quote mark adjacent to a collapsed span sees `(` on its right (moving to
@@ -156,6 +156,7 @@
156
156
  "dashes",
157
157
  "hyphen",
158
158
  "quotes",
159
+ "quote-punctuation",
159
160
  "apostrophe",
160
161
  "symbols",
161
162
  "nbsp"
@@ -19,10 +19,20 @@
19
19
  "quotes": {
20
20
  "type": "object",
21
21
  "additionalProperties": false,
22
- "required": ["primary", "secondary", "elisionIdioms", "elisionClitics"],
22
+ "required": [
23
+ "primary",
24
+ "secondary",
25
+ "punctuationPlacement",
26
+ "elisionIdioms",
27
+ "elisionClitics"
28
+ ],
23
29
  "properties": {
24
30
  "primary": { "$ref": "#/$defs/quotePair" },
25
31
  "secondary": { "$ref": "#/$defs/quotePair" },
32
+ "punctuationPlacement": {
33
+ "enum": ["inside", "none"],
34
+ "description": "Where a comma or full stop goes relative to the closing PRIMARY quotation mark, read only by the opt-in `quote-punctuation` rule (spec 1.21.0). `inside`: the locale's cited convention puts them before the mark, and the rule moves one that was typed after it. `none`: the rule does nothing, either because the locale places them by meaning (a mark that belongs to the quoted material goes inside, one that belongs to the surrounding sentence goes outside, which no scan of code points can decide) or because no convention has been verified; a missing citation is never a licence to guess. `inside` is constrained by scripts/validate-spec.mjs (quote-punctuation.md section 2): the primary close must be a WIDE glyph other than the primary open, `dash.parenthetical` must not be `em-paired`, and neither pair may carry an inner space."
35
+ },
26
36
  "elisionIdioms": {
27
37
  "type": "array",
28
38
  "items": { "$ref": "#/$defs/elisionIdiom" },
@@ -154,6 +164,7 @@
154
164
  "rule": {
155
165
  "enum": [
156
166
  "quotes",
167
+ "quote-punctuation",
157
168
  "dashes",
158
169
  "ranges",
159
170
  "ellipsis",
@@ -29,8 +29,29 @@ module Polytypo
29
29
  def self.locale_data_raw(locale_id)
30
30
  @locale_data_raw ||= {}
31
31
  @locale_data_raw[locale_id] ||=
32
- JSON.parse(File.read(File.join(DATA_DIR, "locales", "#{locale_id}.json")))
32
+ validate_locale_data(
33
+ locale_id,
34
+ JSON.parse(File.read(File.join(DATA_DIR, "locales", "#{locale_id}.json"))),
35
+ )
36
+ end
37
+
38
+ PUNCTUATION_PLACEMENTS = %w[inside none].freeze
39
+
40
+ # quote-punctuation.md 2: `quotes.punctuationPlacement` is required in every locale file and
41
+ # is one of "inside" / "none". A missing or unknown value is a spec-data bug, reported
42
+ # rather than treated as "none".
43
+ def self.validate_locale_data(locale_id, data)
44
+ quotes = data.is_a?(Hash) ? data["quotes"] : nil
45
+ placement = quotes.is_a?(Hash) ? quotes["punctuationPlacement"] : nil
46
+ return data if PUNCTUATION_PLACEMENTS.include?(placement)
47
+
48
+ raise Polytypo::Error.new(
49
+ Polytypo::CODE_MALFORMED_LOCALE_DATA,
50
+ "locale #{locale_id.inspect}: quotes.punctuationPlacement must be \"inside\" or " \
51
+ "\"none\"; received #{placement.inspect}"
52
+ )
33
53
  end
54
+ private_class_method :validate_locale_data
34
55
 
35
56
  def self.lower_ascii?(cp)
36
57
  cp >= LOWER_A && cp <= LOWER_Z
@@ -94,7 +94,7 @@ module Polytypo
94
94
  # spec data in Registry/Locale (ARCHITECTURE.md section 7).
95
95
  module Pipeline
96
96
  # Defaults + opt-out overrides. rules_option is opt-out only (ARCHITECTURE.md section 7):
97
- # it may only disable a default-on rule or enable the one default-off rule ("ranges"). An
97
+ # it may only disable a default-on rule or enable a default-off one ("ranges", "quote-punctuation"). An
98
98
  # unknown key raises POLYTYPO_UNKNOWN_RULE.
99
99
  def self.resolve_rule_plan(rules_option)
100
100
  defaults = Registry.rule_defaults