From 2ce8bebf29f85136725a15ac8c19f509b578b50c Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 31 Aug 2026 21:56:45 -0400 Subject: [PATCH] docs(functions): drop backticks from doc-headers CONTRIBUTING states doc-headers are written as plain text -- the header is read as-is by config-help, by funcsave, and by anyone opening the file, and docs/codespans.py adds the site's inline code spans at render time. 22 files had drifted from that, carrying 41 hand-written spans that reached config-help and the man page as literal backtick characters inside an otherwise verbatim block. The one span whose content ended in a space is requoted rather than dropped, so "read> " keeps reading as a prompt string. --- functions/__config_settings_get_val.fish | 2 +- functions/__config_settings_read_key.fish | 6 +++--- functions/__fish_config_op_enabled.fish | 6 +++--- functions/__fish_user_dots_link.fish | 2 +- functions/__jobrunner_sessions.fish | 2 +- functions/__kitty_logging_has_watcher.fish | 2 +- functions/_agents_init_ensure_gitignore.fish | 4 ++-- functions/_agents_init_install_tools.fish | 2 +- functions/_fish_deps_catalog.fish | 8 ++++---- functions/_fzf_preview_media.fish | 2 +- functions/_prune_terminal_logs.fish | 4 ++-- functions/_zellij_dump_log.fish | 2 +- functions/config-help.fish | 6 +++--- functions/config-update.fish | 2 +- functions/fish-deps.fish | 4 ++-- functions/jobrunner.fish | 8 ++++---- functions/kitty-logging.fish | 6 +++--- functions/mv.fish | 2 +- functions/qc.fish | 2 +- functions/rand_string.fish | 6 +++--- functions/repo-open.fish | 2 +- functions/smart_exit.fish | 2 +- 22 files changed, 41 insertions(+), 41 deletions(-) diff --git a/functions/__config_settings_get_val.fish b/functions/__config_settings_get_val.fish index 6caac00..2670415 100644 --- a/functions/__config_settings_get_val.fish +++ b/functions/__config_settings_get_val.fish @@ -6,7 +6,7 @@ # # DESCRIPTION # Returns the current value of a named variable in the specified scope by -# parsing `set --show` output. Outputs "on", "off", or "DEFAULT" (when +# parsing set --show output. Outputs "on", "off", or "DEFAULT" (when # the variable is not set in that scope). Scope "session" maps to "global" # in fish's internal terminology. # diff --git a/functions/__config_settings_read_key.fish b/functions/__config_settings_read_key.fish index abab5ef..e0903b1 100644 --- a/functions/__config_settings_read_key.fish +++ b/functions/__config_settings_read_key.fish @@ -7,11 +7,11 @@ # DESCRIPTION # Reads a single keypress directly from the controlling terminal in raw # mode and echoes a normalized token naming the key. Bypasses fish's -# `read` builtin, whose interactive line editor swallows Tab and arrow -# keys (and prints a `read> ` prompt) — none of which is usable for a TUI. +# read builtin, whose interactive line editor swallows Tab and arrow +# keys (and prints a "read> " prompt) — none of which is usable for a TUI. # # The terminal is put into raw, no-echo mode with a 0.1s inter-byte timer -# (`stty raw -echo min 1 time 1`) so a multi-byte escape sequence (e.g. +# (stty raw -echo min 1 time 1) so a multi-byte escape sequence (e.g. # an arrow key, ESC [ A) is captured in one read while a lone key returns # promptly. Original terminal settings are always restored before return. # diff --git a/functions/__fish_config_op_enabled.fish b/functions/__fish_config_op_enabled.fish index ec877e2..eb59911 100644 --- a/functions/__fish_config_op_enabled.fish +++ b/functions/__fish_config_op_enabled.fish @@ -17,11 +17,11 @@ # Looks up ":" (site defaults to the empty/unnamed site) # in the generated component registry. No registry entry (unclassified, # or a doc header with no # COMPONENT section) resolves to enabled -- -# the same fail-open default as an explicit `always/on` tag, so +# the same fail-open default as an explicit always/on tag, so # user-authored and third-party functions that never call this guard in # the first place are unaffected, and one that somehow does is never -# silently broken by a missing header. A found `always/off` tag -# disables unconditionally; a found `always/on` tag enables +# silently broken by a missing header. A found always/off tag +# disables unconditionally; a found always/on tag enables # unconditionally, short-circuiting before any other tagged # sub-category is evaluated. Otherwise every tagged sub-category must # pass the cascade (AND semantics). diff --git a/functions/__fish_user_dots_link.fish b/functions/__fish_user_dots_link.fish index f02e583..5bec228 100644 --- a/functions/__fish_user_dots_link.fish +++ b/functions/__fish_user_dots_link.fish @@ -8,7 +8,7 @@ # __fish_user_dots_link # # DESCRIPTION -# Manages the git-ignored `user-dots` convenience symlink in the fish config +# Manages the git-ignored user-dots convenience symlink in the fish config # directory ($__fish_config_dir/user-dots), pointing it at the resolved # $__fish_user_dots_path so the private overlay can be browsed from # ~/.config/fish/. diff --git a/functions/__jobrunner_sessions.fish b/functions/__jobrunner_sessions.fish index 735a7a3..b3958fd 100644 --- a/functions/__jobrunner_sessions.fish +++ b/functions/__jobrunner_sessions.fish @@ -5,7 +5,7 @@ # __jobrunner_sessions [] # # DESCRIPTION -# Parses `tmux list-sessions` or `screen -ls` into machine-readable rows, +# Parses tmux list-sessions or screen -ls into machine-readable rows, # one per active session: name, PID, state, and start time separated by tabs. # Shared by jobrunner and its completions so both agree on what a session is # named. Prints nothing when no sessions exist. diff --git a/functions/__kitty_logging_has_watcher.fish b/functions/__kitty_logging_has_watcher.fish index a49d0eb..3455eee 100644 --- a/functions/__kitty_logging_has_watcher.fish +++ b/functions/__kitty_logging_has_watcher.fish @@ -6,7 +6,7 @@ # # DESCRIPTION # Succeeds (returns 0) when the top-level kitty.conf contains an active -# (non-commented) `watcher` directive — whether the fish-config managed one or +# (non-commented) watcher directive — whether the fish-config managed one or # a user's own. Used to suppress the setup reminder and to inform status. # # EXIT STATUS diff --git a/functions/_agents_init_ensure_gitignore.fish b/functions/_agents_init_ensure_gitignore.fish index 3df0fd3..45d4c9f 100644 --- a/functions/_agents_init_ensure_gitignore.fish +++ b/functions/_agents_init_ensure_gitignore.fish @@ -6,9 +6,9 @@ # # DESCRIPTION # Appends any patterns not already covered by the project's .gitignore. -# Uses `git check-ignore` for accurate rule matching (catches wildcards +# Uses git check-ignore for accurate rule matching (catches wildcards # and parent-dir globs). Falls back to a plain string search when the -# root is not a git repository. Leading `/` is stripped from each pattern +# root is not a git repository. Leading / is stripped from each pattern # before the path-based check so root-anchored patterns (e.g. /AGENTS.md) # are matched correctly. # diff --git a/functions/_agents_init_install_tools.fish b/functions/_agents_init_install_tools.fish index 3c544af..5491971 100644 --- a/functions/_agents_init_install_tools.fish +++ b/functions/_agents_init_install_tools.fish @@ -7,7 +7,7 @@ # DESCRIPTION # Copies the canonical version-bump script and git hook shims from # fish-config's scripts/agents-tools/ into /.agents-tools/, -# refreshing them when the shipped `agents-tools-version:` marker is newer +# refreshing them when the shipped agents-tools-version: marker is newer # than the installed copy. Files are made executable. Idempotent: prints # nothing when the installed tooling is already current, or a short summary # line when it installed or updated the tooling. diff --git a/functions/_fish_deps_catalog.fish b/functions/_fish_deps_catalog.fish index 41aa526..d466fbe 100644 --- a/functions/_fish_deps_catalog.fish +++ b/functions/_fish_deps_catalog.fish @@ -18,13 +18,13 @@ # conveniences (e.g. backs one wrapper # function) that only matter if you already # use that specific tool. Skipped by -# `fish-deps install`/`sync` unless -# `--optional` (or `--all`) is passed. +# fish-deps install/sync unless +# --optional (or --all) is passed. # term Terminal Emulators — GPU-accelerated terminal emulators # (kitty, wezterm) that only matter if one # of them is your actual terminal. Skipped -# by `fish-deps install`/`sync` unless -# `--terminals` (or `--all`) is passed. +# by fish-deps install/sync unless +# --terminals (or --all) is passed. # int Integrations — opt-in third-party services requiring # their own account/setup (wakatime, # tailscale). diff --git a/functions/_fzf_preview_media.fish b/functions/_fzf_preview_media.fish index 375cdfd..76abc4f 100644 --- a/functions/_fzf_preview_media.fish +++ b/functions/_fzf_preview_media.fish @@ -9,7 +9,7 @@ # by a desktop file manager (Dolphin, Nautilus, GNOME Videos, ...) in the # freedesktop thumbnail cache and renders it via _fzf_preview_image if # found. Otherwise falls back to ffprobe-formatted metadata (duration, -# codec, resolution, tags) when ffprobe is installed, or plain `file` +# codec, resolution, tags) when ffprobe is installed, or plain file # output as a last resort. Neither the thumbnail cache lookup nor ffprobe # are tracked in fish-deps: both are best-effort, matching how the # image-preview tool chain (kitten/chafa/viu/timg) is already handled. diff --git a/functions/_prune_terminal_logs.fish b/functions/_prune_terminal_logs.fish index f5c4b41..5a8b546 100644 --- a/functions/_prune_terminal_logs.fish +++ b/functions/_prune_terminal_logs.fish @@ -11,9 +11,9 @@ # modification time, so the most recently written logs are kept — actively # appended logs (e.g. a tmux pipe-pane stream) survive. # -# Uses `command ls`/`command rm` to bypass the C1 shadows: the bare `ls` is +# Uses command ls/command rm to bypass the C1 shadows: the bare ls is # the eza wrapper, which injects OSC-8 hyperlink escapes into paths, and the -# bare `rm` is the trash wrapper. The glob is expanded via `set` first so a +# bare rm is the trash wrapper. The glob is expanded via set first so a # no-match (empty dir / first run) yields an empty list instead of a hard # "No matches for wildcard" error. # diff --git a/functions/_zellij_dump_log.fish b/functions/_zellij_dump_log.fish index 46ab9bb..0808b5d 100644 --- a/functions/_zellij_dump_log.fish +++ b/functions/_zellij_dump_log.fish @@ -11,7 +11,7 @@ # Captures the current Zellij pane's scrollback to a timestamped log in # SCROLLBACK_HISTORY_DIR (default ~/.terminal_history). Zellij has no live # output-streaming facility like tmux's pipe-pane, so this performs a one-shot -# `zellij action dump-screen --full` — intended to run on shell exit. Old +# zellij action dump-screen --full — intended to run on shell exit. Old # zellij_*.log files are pruned via _prune_terminal_logs to stay within # SCROLLBACK_HISTORY_MAX_FILES. # diff --git a/functions/config-help.fish b/functions/config-help.fish index 562874e..8460acb 100644 --- a/functions/config-help.fish +++ b/functions/config-help.fish @@ -22,7 +22,7 @@ # in the default browser via xdg-open — deep links to a section aren't # supported there, so if a keyword is given a note points you to the site's # search box instead. Pass --man / -m to open the compiled man page -# (docs/fish-config.1) via `man -l`; if a section keyword is given, the +# (docs/fish-config.1) via man -l; if a section keyword is given, the # pager opens at the nearest match. Pass --help or -h for usage and the # navigation key reference. # @@ -52,9 +52,9 @@ # config-help pkg --man # # NOTES -# The preferred invocation is `help config [...]` — this function is +# The preferred invocation is help config [...] — this function is # registered as a handler in the help wrapper so that syntax works -# transparently. Direct `config-help` calls are also valid. +# transparently. Direct config-help calls are also valid. function config-help --description 'Open the offline fish shell configuration manual' set -l doc_file "$__fish_config_dir/docs/fish-config.md" set -l idx_file "$__fish_config_dir/docs/fish-config.index" diff --git a/functions/config-update.fish b/functions/config-update.fish index 37bf5f4..1d3fc8a 100644 --- a/functions/config-update.fish +++ b/functions/config-update.fish @@ -11,7 +11,7 @@ # Pulls the latest fish shell configuration from the upstream repository # into ~/.config/fish. Git output is suppressed; status is reported # through colored messages. After a successful pull the function prints a -# short summary of changed files; run `exec fish` to reload the shell. +# short summary of changed files; run exec fish to reload the shell. # # ARGUMENTS # -h, --help Show this help message and exit diff --git a/functions/fish-deps.fish b/functions/fish-deps.fish index b0860e6..bf9839e 100644 --- a/functions/fish-deps.fish +++ b/functions/fish-deps.fish @@ -29,10 +29,10 @@ # Optional btop, dust, duf, prettyping, go, lazygit, # lazydocker, docker, yt-dlp, screen — single-purpose # wrapper conveniences that only matter if you -# already use that tool; skipped by `install`/`sync` +# already use that tool; skipped by install/sync # unless --optional (or --all) is passed # Terminal Emulators kitty, wezterm — only matter if one of them is -# your actual terminal; skipped by `install`/`sync` +# your actual terminal; skipped by install/sync # unless --terminals (or --all) is passed # Integrations wakatime, tailscale # diff --git a/functions/jobrunner.fish b/functions/jobrunner.fish index 33951d0..1fffdf6 100644 --- a/functions/jobrunner.fish +++ b/functions/jobrunner.fish @@ -15,13 +15,13 @@ # Runs, lists, inspects, re-attaches to, and terminates named background # jobs using tmux or GNU screen as the process engine. Unlike bkg and # detach, which discard output, a jobrunner job keeps a live terminal you -# can return to later — it survives closing the shell, and `attach` +# can return to later — it survives closing the shell, and attach # restores it in any subsequent session. # Run and manage named background jobs. Jobs are detached from the shell # and backed by tmux (preferred) or GNU screen. # -# If the job name is omitted when starting a new job (e.g. `jobrunner sleep 1`), -# a memorable, random name (like `sleepy-badger`) will be generated. +# If the job name is omitted when starting a new job (e.g. jobrunner sleep 1), +# a memorable, random name (like sleepy-badger) will be generated. # # SUBCOMMANDS # run, -r, --run [-n ] Start a new background job @@ -49,7 +49,7 @@ # Detach from an attached job with Ctrl-A then D; the job keeps running. # Commands are executed directly rather than through a shell, so pipes and # redirections must be wrapped explicitly, e.g. -# `jobrunner run sync fish -c 'a | b'`. +# jobrunner run sync fish -c 'a | b'. function jobrunner --description 'Manage detached background jobs with tmux or GNU screen' set -l c_head (set_color --bold cyan) set -l c_cmd (set_color --bold) diff --git a/functions/kitty-logging.fish b/functions/kitty-logging.fish index 3ab50ae..dbff8d9 100644 --- a/functions/kitty-logging.fish +++ b/functions/kitty-logging.fish @@ -12,11 +12,11 @@ # # DESCRIPTION # Manages the fish-config Kitty scrollback watcher that powers C5 logging. -# `install` symlinks the canonical watcher into the Kitty config dir (so it +# install symlinks the canonical watcher into the Kitty config dir (so it # always tracks the source) and wires it into kitty.conf via a # sentinel-marked managed block, commenting out any conflicting active -# watcher line to avoid double-capture. `uninstall` reverses it. `status` -# reports wiring, installed watcher version, and C5 logging state. `dismiss` +# watcher line to avoid double-capture. uninstall reverses it. status +# reports wiring, installed watcher version, and C5 logging state. dismiss # silences the per-session setup reminder. # # Runtime capture stays governed by the C5 .logging_disabled sentinel, so diff --git a/functions/mv.fish b/functions/mv.fish index e8e4b8b..82efcf1 100644 --- a/functions/mv.fish +++ b/functions/mv.fish @@ -13,7 +13,7 @@ # DESCRIPTION # Wraps mv to automatically collapse nested directories of the same name. # When extracting archives results in redundant structures (e.g., -# themes/themes/), calling `mv themes/themes themes` will gracefully +# themes/themes/), calling mv themes/themes themes will gracefully # move the inner contents up one level and remove the empty outer shell. # # Opinionated component (C1): when disabled via __fish_config_op_aliases, diff --git a/functions/qc.fish b/functions/qc.fish index 9cb8a55..f598ec0 100644 --- a/functions/qc.fish +++ b/functions/qc.fish @@ -15,7 +15,7 @@ # scripts/cli-agent.md to $XDG_CONFIG_HOME/aichat/roles/cli.md. Inherits # every aichat flag and tab completion (--wraps aichat); passing --role/-r # overrides the default role, so qc forwards to aichat unchanged. The -# function is only defined when aichat is installed. Run `qc --help` for +# function is only defined when aichat is installed. Run qc --help for # aichat's full flag reference with the command name rewritten to qc. # # ARGUMENTS diff --git a/functions/rand_string.fish b/functions/rand_string.fish index b150c02..c5b0312 100644 --- a/functions/rand_string.fish +++ b/functions/rand_string.fish @@ -10,9 +10,9 @@ # DESCRIPTION # Generates a random, memorable string using a sequence of specified word # categories and formatting modifiers. Words are pulled from curated -# plain-text databases bundled in `data/words/`. +# plain-text databases bundled in data/words/. # -# Modifiers like `--separator` and `--case` are evaluated sequentially and +# Modifiers like --separator and --case are evaluated sequentially and # apply only to the components that follow them. # # Supported Components: @@ -35,7 +35,7 @@ # rand_string literal=TEST --separator=underscore verb noun # # NOTES -# Falls back to `random choice` if GNU `shuf` is missing, but `shuf` is +# Falls back to random choice if GNU shuf is missing, but shuf is # much faster for files with >1000 lines. function rand_string --description 'Generate random, memorable strings from curated word databases' set -l c_head (set_color --bold cyan) diff --git a/functions/repo-open.fish b/functions/repo-open.fish index 9cb6b7e..60eee02 100644 --- a/functions/repo-open.fish +++ b/functions/repo-open.fish @@ -12,7 +12,7 @@ # repo-open --help # # DESCRIPTION -# Opens the web page for the current repository's `origin` remote in a +# Opens the web page for the current repository's origin remote in a # browser (via open-url). Deep-links to the current branch when it exists # on the remote, falling back to the remote's default branch (main/master) # otherwise, and to the current sub-directory when invoked below the repo diff --git a/functions/smart_exit.fish b/functions/smart_exit.fish index 6b509e7..4d34c61 100644 --- a/functions/smart_exit.fish +++ b/functions/smart_exit.fish @@ -31,7 +31,7 @@ # # NOTES # The exit builtin is wired to smart_exit for interactive sessions. Typing -# `exit` or Ctrl+D behaves identically to calling smart_exit directly. +# exit or Ctrl+D behaves identically to calling smart_exit directly. function smart_exit --description 'Capture colorized scrollback before exiting, with pruning and safe overrides' # Opinionated guard (C3): exit plainly when overrides are disabled. # This composes with Task #4's __fish_config_enable_logging, which will