feat(help): integrate config-help into fish's help command
Rename config_help → config-help and add a help wrapper that intercepts 'help config [section]', forwarding sub-topics to config-help. Update README and docs to use 'help config' as the preferred interface so offline docs feel like a natural extension of fish's built-in help system.
This commit is contained in:
@@ -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 <keyword>` | Jump directly to a section matching the keyword |
|
||||
| `help config` | Open the offline manual in the best available pager |
|
||||
| `help config <keyword>` | 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:
|
||||
|
||||
|
||||
@@ -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 ─────────────────────────────────────────────────
|
||||
|
||||
+14
-11
@@ -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.
|
||||
|
||||
@@ -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)"
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user