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.
This commit is contained in:
@@ -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.
|
||||
#
|
||||
|
||||
@@ -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.
|
||||
#
|
||||
|
||||
@@ -17,11 +17,11 @@
|
||||
# Looks up "<identity>:<site>" (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).
|
||||
|
||||
@@ -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/.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
# __jobrunner_sessions [<tool>]
|
||||
#
|
||||
# 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
#
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
# DESCRIPTION
|
||||
# Copies the canonical version-bump script and git hook shims from
|
||||
# fish-config's scripts/agents-tools/ into <agents_dir>/.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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
#
|
||||
|
||||
@@ -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.
|
||||
#
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
#
|
||||
|
||||
@@ -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 <name>] <cmd> 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)
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -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,
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user