linebender / linebender/parley
complex-scripts feature is off by default and undocumented — CJK line breaking silently broken
- Dominant language
- Rust
- Stars
- 736
- Forks
- 120
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 53
Description
**Target repo**: https://github.com/linebender/parley
**Type**: Documentation / DX (possibly feature-default discussion)
**Tested version**: parley 0.11.1 (latest stable at time of writing)
## Summary
With the default feature set, parley's line segmentation has no dictionary model for
Chinese/Japanese. At runtime the console is flooded with:
```
ICU4X data error: No segmentation model for complex script: Chinese/Japanese
```
and CJK text either fails to wrap correctly or whole paragraphs are treated as
unbreakable runs (they visually "disappear" or overflow). Nothing in the README or
crate-level docs mentions the `complex-scripts` cargo feature, so a new user has no
way to connect the symptom to the switch.
Enabling the feature fixes it immediately:
```toml
parley = { version = "0.11.1", features = ["complex-scripts"] }
```
## Why this matters
Anyone using parley for Chinese/Japanese/Thai text hits this on day one. Downstream
evidence: Bevy's Chinese text editing produced the same class of problem before the
feature was wired through (documented in the community, e.g.
https://zool.me/posts/中文一改就刷屏/). We hit it building a CJK EPUB reader
(parley 0.11 + vello 0.10 + wgpu, Windows), reproduced with plain
`ranged_builder(...) -> build() -> break_all_lines(width)` on a Chinese paragraph.
## Proposal
1. **Docs (cheap, uncontroversial)**: add a "Text segmentation / CJK" note to the
README and the feature list in Cargo.toml, stating that `complex-scripts` is
required for dictionary-based line breaking of CJK/Thai/Khmer/Lao/Myanmar.
2. **Runtime warning (nice to have)**: when segmentation is requested for a complex
script while the feature is disabled, emit a one-time `debug!`/`warn!` pointing at
the feature flag, instead of only the ICU4X data error.
3. **Design question**: should `complex-scripts` be a default feature? We understand
the ICU dictionary data costs binary size, so we're not pushing — but a documented,
discoverable switch would already resolve most of the pain.
## Environment
- Windows 11, Rust stable-x86_64-pc-windows-msvc, wgpu 29 (via vello 0.10)
- Text: Simplified Chinese light-novel prose (CJK + full-width punctuation + ASCII mix)
---
*Drafted from our engineering log; happy to send a docs PR if maintainers agree on wording.*
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the README and Cargo.toml feature list, then reproduce the reported behavior using ranged_builder(...)->build()->break_all_lines(width) with a CJK paragraph. Document that the complex-scripts feature is required for dictionary-based CJK and related script line breaking, including the feature configuration. Treat the runtime warning and default-feature question as separate follow-up decisions unless maintainers expand the scope.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, internationalization
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100