diff --git a/README.md b/README.md index 837bde5..c6eee83 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ This config layers on top of the CachyOS base Fish configuration and adds: │ └── zoxide.fish # Zoxide z/zi aliases ├── docs/ # Offline documentation │ ├── fish-config.md # Primary offline reference manual (terminal-readable) -│ └── fish-config.index # Section index for config_help navigation +│ └── fish-config.index # Section index for `help config` navigation ├── functions/ # Custom functions (one per file) ├── completions/ # Custom tab completions ├── integrations/ # Integration scripts @@ -314,12 +314,14 @@ A curated offline reference manual is available at `docs/fish-config.md`. It cov | Command | Description | |---|---| -| `config_help` | Open the offline manual in the best available pager | -| `config_help ` | Jump directly to a section matching the keyword | +| `help config` | Open the offline manual in the best available pager | +| `help config ` | Jump directly to a section matching the keyword | The viewer falls back through: **ov** (syntax highlight + section navigation) → **bat** (syntax highlight) → **man -l** (pre-compiled man page) → **less** → **cat**. -Examples: `config_help keybindings` · `config_help pkg` · `config_help fish-deps` · `config_help abbreviations` +Examples: `help config keybindings` · `help config pkg` · `help config fish-deps` · `help config abbreviations` + +> **Tip:** `help config` is the preferred way to access offline docs — it integrates naturally with fish's built-in `help` command. The underlying `config-help` function is still available directly if needed. You can also read the documentation as a standard man page — the symlink and `MANPATH` are set up automatically on shell start: diff --git a/docs/fish-config.index b/docs/fish-config.index index b26b879..74e80b1 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -2,7 +2,7 @@ # Format: keyword=exact heading text as it appears in fish-config.md # Multiple keywords may map to the same heading. # Update this file whenever headings are added, removed, or renamed. -# config_help uses this for fast exact lookups; unknown keywords fall back +# config-help uses this for fast exact lookups; unknown keywords fall back # to a normalized heading scan automatically. # ── Top-level ───────────────────────────────────────────────── diff --git a/docs/fish-config.md b/docs/fish-config.md index 3d1244f..b93c14c 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -12,15 +12,18 @@ fish-config - personal fish shell configuration for Fish 4.x with modern CLI too # SYNOPSIS - config_help [SECTION] + help config [SECTION] Open this manual in the best available pager. Optionally jump to a section by keyword: - config_help keybindings - config_help pkg - config_help abbreviations - config_help logs + help config keybindings + help config pkg + help config abbreviations + help config logs + +The `help config` syntax integrates with fish's built-in help command. +The underlying `config-help` function is also available directly. # DESCRIPTION @@ -1213,7 +1216,7 @@ calls fisher update as its first step. ## With ov (recommended) - config_help + help config ov renders the Markdown with syntax highlighting and section-based navigation. @@ -1247,10 +1250,10 @@ a completely separate command. Do not mix them up. ## Jumping to a section - config_help keybindings - config_help abbreviations - config_help pkg - config_help logs - config_help fish-deps + help config keybindings + help config abbreviations + help config pkg + help config logs + help config fish-deps The keyword is matched case-insensitively against section headings. diff --git a/functions/config_help.fish b/functions/config-help.fish similarity index 92% rename from functions/config_help.fish rename to functions/config-help.fish index bf03721..323e890 100644 --- a/functions/config_help.fish +++ b/functions/config-help.fish @@ -2,8 +2,8 @@ # SPDX-License-Identifier: AGPL-3.0-or-later # SYNOPSIS -# config_help [section] -# config_help --help +# config-help [section] +# config-help --help # # DESCRIPTION # Opens the offline fish shell configuration manual in the best available @@ -24,24 +24,24 @@ # 1 Documentation file not found # # EXAMPLE -# config_help -# config_help keybindings -# config_help pkg -# config_help fish-deps -# config_help --help -function config_help --description 'Open the offline fish shell configuration manual' +# config-help +# config-help keybindings +# config-help pkg +# config-help fish-deps +# config-help --help +function config-help --description 'Open the offline fish shell configuration manual' # ── --help / -h ────────────────────────────────────────────── if contains -- --help $argv; or contains -- -h $argv set_color --bold - echo config_help + echo config-help set_color normal echo " — view the offline fish shell configuration manual" echo "" set_color --bold brblue echo USAGE set_color normal - echo " config_help "(set_color yellow)"[section]"(set_color normal) - echo " config_help "(set_color yellow)"--help"(set_color normal) + echo " config-help "(set_color yellow)"[section]"(set_color normal) + echo " config-help "(set_color yellow)"--help"(set_color normal) echo "" set_color --bold brblue echo ARGUMENTS @@ -54,11 +54,11 @@ function config_help --description 'Open the offline fish shell configuration ma set_color --bold brblue echo EXAMPLES set_color normal - echo " "(set_color green)"config_help"(set_color normal)" open at top" - echo " "(set_color green)"config_help keybindings"(set_color normal)" jump to Key Bindings section" - echo " "(set_color green)"config_help pkg"(set_color normal)" jump to the pkg function entry" - echo " "(set_color green)"config_help fish-deps"(set_color normal)" jump to fish-deps" - echo " "(set_color green)"config_help abbreviations"(set_color normal)" jump to Abbreviations section" + echo " "(set_color green)"config-help"(set_color normal)" open at top" + echo " "(set_color green)"config-help keybindings"(set_color normal)" jump to Key Bindings section" + echo " "(set_color green)"config-help pkg"(set_color normal)" jump to the pkg function entry" + echo " "(set_color green)"config-help fish-deps"(set_color normal)" jump to fish-deps" + echo " "(set_color green)"config-help abbreviations"(set_color normal)" jump to Abbreviations section" echo "" set_color --bold brblue echo "NAVIGATION (ov pager)" diff --git a/functions/help.fish b/functions/help.fish new file mode 100644 index 0000000..32a5659 --- /dev/null +++ b/functions/help.fish @@ -0,0 +1,47 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# help [topic] [sub-topic...] +# +# DESCRIPTION +# Wraps the built-in Fish help command. Intercepts the specific topic "config" +# and forwards any subsequent sub-topics/arguments straight to the custom +# 'config-help' utility. For all other topics, it forwards the arguments +# intact to the original, built-in system help utility. +# +# ARGUMENTS +# topic Optional string representing the primary help subject (e.g., "config"). +# sub-topic Optional additional arguments passed exclusively to 'config-help'. +# +# RETURNS +# 0 Successful execution of config-help or the original system help command. +# >0 Failure status returned by the underlying help utilities. +# +# NOTES +# To prevent infinite recursion, the wrapper must backup the native system function +# on the first run. Because Fish lazy-loads functions dynamically, we explicitly +# source the system file and clone it to '__original_help' if it doesn't already exist. +# +# EXAMPLE +# help config keys +# # Executes: config-help keys +# +# help string +# # Forwards to the standard fish documentation for 'string' + +# --- Initialization & Backup --- +if not functions -q __original_help + source $__fish_data_dir/functions/help.fish + functions -c help __original_help +end + +# --- Wrapper Definition --- +function help --wraps help --description "Custom wrapper to intercept 'help config'" + if test "$argv[1]" = config + # Pass every argument after 'config' to the config-help function + config-help $argv[2..] + else + __original_help $argv + end +end