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:
2026-06-06 22:31:24 -04:00
parent cf56f58dcd
commit 569d17a342
5 changed files with 84 additions and 32 deletions
@@ -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)"
+47
View File
@@ -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