diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb0ad6d..e61a79b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/docs/site/README.md b/docs/site/README.md index a7d25c6..5fcee38 100644 --- a/docs/site/README.md +++ b/docs/site/README.md @@ -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 `` 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 `` 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 diff --git a/functions/config-help.fish b/functions/config-help.fish index 8460acb..fa75aed 100644 --- a/functions/config-help.fish +++ b/functions/config-help.fish @@ -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