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 -6
View File
@@ -25,8 +25,13 @@ first if you've touched a header or a manual page.
Function headers are read as plain text (by `config-help`, by `funcsave`,
by anyone opening the `.fish` file), so they're authored without backticks
— `-a/--all`, not `` `-a`/`--all` ``. `docs/codespans.py` puts the
backticks on at render time, as the last step of `prettify()`, so only the
site sees them.
backticks on at render time, as the last step of `prettify()`.
`build_concat()` runs the same pass, so the man page and `config-help`
mark code the way the site does rather than only where the SSOT happened
to backtick something by hand. `config-help` then renders those spans
bold and drops the delimiters, since a terminal pager would otherwise
show them as literal punctuation.
It recognises flags, `$vars`, `SCREAMING_SNAKE` env vars, snake_case
identifiers (`__fish_config_op_aliases`, `fish_greeting`), paths and
@@ -41,10 +46,14 @@ Names that also read as English (`find`, `top`, `screen`) are listed in
where position already proves they're a command. Add to that list rather
than removing a rule if a wrap ever reads wrong.
Fenced blocks, existing code spans, headings, link targets, URLs,
component markup, and `<FileTree>` bodies are never touched. Leaving a
token alone is always the safe outcome, so every rule bails out when it
isn't sure.
Fenced blocks, indented blocks, existing code spans, headings, link
targets, URLs, component markup, and `<FileTree>` bodies are never
touched. Leaving a token alone is always the safe outcome, so every rule
bails out when it isn't sure.
Indented blocks matter only to the concat — `prettify()` has already
fenced them by the time the site is rendered — but there they are the
table of contents and every section 5 entry, which must stay verbatim.
## llms.txt