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:
+15
-2
@@ -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
|
||||
|
||||
|
||||
+15
-6
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user