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
+33 -7
View File
@@ -247,6 +247,22 @@ function config-help --description 'Open the offline fish shell configuration ma
set -l nav_hint \
" \033[2mNAVIGATION: [ Space=next section ^=prev Alt+u=sections /=search q=quit ]\033[0m"
# ── Inline code spans ────────────────────────────────────────
# The document carries backticks for pandoc and the docs site, but
# nothing in this chain consumes them: bat dims the delimiters and
# leaves the content the same colour as the surrounding prose, so
# they arrive as literal punctuation. Render each span bold instead.
#
# Two forms are matched. After bat, every backtick carries its own
# SGR sequence, and a fence survives because it puts three of them
# inside one sequence. On raw Markdown a fence survives because it
# offers no non-backtick content to capture. Both substitutions are
# line-preserving, so the tail-slice below still lands on the
# requested section.
set -l span_ansi '\e\[[0-9;]*m`\e\[0m(.*?)\e\[[0-9;]*m`\e\[0m'
set -l span_raw '`([^`]+)`'
set -l span_bold (printf '\e[1m$1\e[0m')
# ── Viewer fallback chain ────────────────────────────────────
# When jumping to a section, slice the file from start_line so ov
# opens with that section at the top without needing --pattern.
@@ -261,12 +277,14 @@ function config-help --description 'Open the offline fish shell configuration ma
begin
printf "$nav_hint\n"
bat --color=always --style=plain --language=markdown "$doc_file" \
| tail -n +$start_line
| tail -n +$start_line \
| string replace -ra $span_ansi $span_bold
end | ov $ov_args
else
begin
printf "$nav_hint\n"
bat --color=always --style=plain --language=markdown "$doc_file"
bat --color=always --style=plain --language=markdown "$doc_file" \
| string replace -ra $span_ansi $span_bold
end | ov $ov_args
end
@@ -279,12 +297,13 @@ function config-help --description 'Open the offline fish shell configuration ma
if test $start_line -gt 1
begin
printf "$nav_hint\n"
tail -n +$start_line "$doc_file"
tail -n +$start_line "$doc_file" \
| string replace -ra $span_raw $span_bold
end | ov $ov_args
else
begin
printf "$nav_hint\n"
cat "$doc_file"
string replace -ra $span_raw $span_bold <"$doc_file"
end | ov $ov_args
end
@@ -295,16 +314,23 @@ function config-help --description 'Open the offline fish shell configuration ma
echo "note: bat pager — use / to search for your section" >&2
set_color normal
end
bat --language=markdown --paging=always "$doc_file"
# bat owns the pager here, so the spans are flattened on the way
# in rather than styled on the way out — bat would escape any
# SGR sequence handed to it as input.
string replace -ra $span_raw '$1' <"$doc_file" \
| bat --language=markdown --paging=always
# Pre-compiled man page (generated by CI after merge).
# pandoc consumed the backticks when it built this, so there is
# nothing to strip.
else if test -f "$man_file"
man -l "$man_file"
else if type -q less
less +"$start_line" "$doc_file"
string replace -ra $span_raw $span_bold <"$doc_file" \
| less -R +"$start_line"
else
cat "$doc_file"
string replace -ra $span_raw $span_bold <"$doc_file"
end
end