From 3648e37a1ebf27a6c7656641e87dbf7fcc725962 Mon Sep 17 00:00:00 2001 From: Mikhail Chusavitin Date: Wed, 29 Apr 2026 10:30:27 +0300 Subject: [PATCH] Update bible submodule to remote HEAD, preserve ascii-safe-text contract locally Co-Authored-By: Claude Sonnet 4.6 --- bible | 2 +- .../patterns/ascii-safe-text/contract.md | 31 +++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 bible-local/rules/patterns/ascii-safe-text/contract.md diff --git a/bible b/bible index 98448c9..d2600f1 160000 --- a/bible +++ b/bible @@ -1 +1 @@ -Subproject commit 98448c993f76622a814ed89538f8ea474b2a515d +Subproject commit d2600f12799451cd5233a8d2c0e3235d1e7d25ab diff --git a/bible-local/rules/patterns/ascii-safe-text/contract.md b/bible-local/rules/patterns/ascii-safe-text/contract.md new file mode 100644 index 0000000..b2124a2 --- /dev/null +++ b/bible-local/rules/patterns/ascii-safe-text/contract.md @@ -0,0 +1,31 @@ +# Contract: ASCII-Safe Text in Scripts and Boot Configs + +Version: 1.0 + +## Principle + +Shell scripts, bootloader configs, and any text rendered on serial/SOL consoles must use only printable ASCII characters. Non-ASCII Unicode — including typographic punctuation such as the em-dash (U+2014 `—`), en-dash (U+2013 `–`), curly quotes, and ellipsis (U+2026 `…`) — breaks rendering on serial terminals, GRUB text/serial mode, IPMI SOL, and tooling that assumes ASCII. + +## Rules + +- Never use em-dash (`—`) or en-dash (`–`) in any shell script, GRUB config, syslinux/isolinux config, or service unit file. Use ASCII double-hyphen `--` or single hyphen `-` instead. +- Never use curly quotes (`"` `"` `'` `'`) in shell scripts or configs. Use straight quotes `"` and `'`. +- Never use the Unicode ellipsis (`…`). Use `...`. +- GRUB `menuentry` and `submenu` titles must be ASCII-only — GRUB serial terminal output is ASCII; non-ASCII characters render as garbage or are dropped. +- Comments in GRUB theme files (`.txt`) must also be ASCII-only, as GRUB may parse the entire file. + +## Why + +GRUB renders menus over both `gfxterm` (graphical, Unicode-capable) and `serial` (ASCII-only) simultaneously when `terminal_output gfxterm serial` is set. The serial output — used by IPMI SOL and BMC remote consoles — cannot display multi-byte UTF-8 sequences and shows raw bytes or drops characters. A menuentry title `"EASY-BEE — GSP=off"` appears as `"EASY-BEE â€" GSP=off"` or `"EASY-BEE GSP=off"` on SOL, making the menu unreadable. + +## Anti-patterns + +- `menuentry "EASY-BEE — GSP=off"` — em-dash in GRUB title +- `# bee logo — centered` — em-dash in GRUB theme comment +- `echo "done — reboot"` in a shell script displayed over serial + +## Correct form + +- `menuentry "EASY-BEE -- GSP=off"` +- `# bee logo - centered` +- `echo "done - reboot"`