feat(help): render inline code spans instead of printing backticks

config-help pipes the manual through bat, which dims the backticks and
leaves the span content the same colour as the prose around it -- so a
delimiter carried no information and every span cost the reader two
literal characters. 1236 of them across the document.

Each span is now rendered bold and the delimiters dropped, in every
branch of the viewer chain:

- ov + bat, and ov alone, style the spans (bat's output wraps each
  backtick in its own SGR sequence; raw Markdown is matched directly)
- bat alone flattens them on the way in instead, because bat escapes
  any SGR sequence handed to it as input
- less and cat style them, less gaining -R to render the result
- man -l needs nothing; pandoc consumed the backticks at build time

Both substitutions are line-preserving, so the tail-slice that opens
the pager on a requested section still lands on it.
This commit is contained in:
2026-08-31 22:02:37 -04:00
parent f0de5378fe
commit 577ad993ea
3 changed files with 63 additions and 15 deletions
+15 -2
View File
@@ -243,8 +243,21 @@ Write doc-headers as plain text — no backticks. `-a/--all`,
`__fish_config_op_aliases` and `~/.config/fish/config.fish` are typed
bare, because the header is also read as-is by `config-help` and by
anyone opening the file. `docs/codespans.py` adds the inline code spans
the docs site wants when it renders, so the SSOT never carries them; see
`docs/site/README.md` for which shapes it recognises.
when it renders, so the SSOT never carries them; see
`docs/site/README.md` for which shapes it recognises. That pass runs for
every output — the site, the man page and `config-help` — so a token is
typeset the same way wherever it is read.
Two rules apply to backticks you write under `docs/manual/` as well:
- **Never inside an indented block.** A four-space block is verbatim in
every renderer, so a backtick there is a literal character on the page
rather than markup.
- **Never wrapped across a line break.** Markdown accepts a span split
over two lines, but `config-help` pairs backticks one line at a time
and would show the halves literally. Reflow the sentence instead.
`docs/verify-manual.py` enforces both.
## Testing