linebender / linebender/parley

complex-scripts feature is off by default and undocumented — CJK line breaking silently broken

Open Beginner friendly
#773 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.