32 lines
1.8 KiB
Markdown
32 lines
1.8 KiB
Markdown
# 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"`
|