#1939·rio

docs: rio.5 man page is stale after the font stack rewrite (fonts.emoji removed; size unit/default wrong)

Author: abcfy2Created Sep 15, 2026Updated Sep 15, 2026

extra/man/rio.5.scd (the source of the shipped rio(5) man page) has fallen behind the font stack rewrite and now documents configuration that no longer exists, plus a wrong default/unit. Two concrete spots:

1. fonts.emoji section documents removed configuration

The man page still says:

*emoji* = { family = _"<string>"_ }

	Emoji font configuration.

	Default: Built-in Twemoji font

But on current main:

  • SugarloafFonts (sugarloaf/src/font/fonts.rs) has no emoji field
  • a codebase-wide search for twemoji matches only rio.5.scd itself — the bundled font resources are gone (e.g. sugarloaf/src/font/ at v0.1.7 still had fallbacks/ and resources/ directories; they no longer exist on main)
  • emoji rendering now relies on system font fallback (fontconfig) plus the explicit fonts.symbol-map mapping, which the man page already documents separately

#1357 (closed 2026-05-19, "Emoji font configuration does not consistently apply") is consistent with this: the fonts.emoji knob stopped doing anything around the font stack rework.

2. fonts.size: wrong unit and wrong default

The man page says:

*size* = _<float>_

	Font size in points.

	Default: _18.0_

Actual behavior on main:

  • default is 14 (default_font_size() in sugarloaf/src/font/fonts.rs)
  • the value is interpreted as logical pixels, not points: it is passed straight through to the renderer (s.font_size = config.fonts.size, frontends/rioterm/src/screen/mod.rs), there is no 96/72 pt→px conversion anywhere in the pipeline, and glyph metrics are computed as physical = size × scale (see the comment "Metrics::calc at physical font_size scale" in frontends/rioterm/src/layout/compute_tests.rs)

User-visible consequence: at the same nominal value, rio renders text ~25% smaller than GTK-based terminals (e.g. ghostty's font-size = 13 is 13 pt → 17.33 logical px, while rio's size = 13 is used as 13 logical px directly). Side-by-side this is quite obvious and has confused users into inflating size.

Suggested fix

Update rio.5.scd: drop the emoji section, and document size as logical pixels with default 14. Longer term, generating the man page from the same source as the config documentation site would prevent this kind of drift.

Verified against main (post-0.5.27) and the Arch Linux rio package man page.