diff --git a/README.md b/README.md index 4a27f46..432e434 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,8 @@ To browse the docs from the terminal: |---|---| | `help config` | Open the terminal manual in the best available pager | | `help config ` | Jump directly to a section matching the keyword | -| `config-help --html` | Open the pre-built HTML docs in the default browser | -| `config-help --man` | Open the compiled man page via `man -l` | +| `help config --html` | Open the pre-built HTML docs in the default browser | +| `help config --man` | Open the compiled man page via `man -l` | The pager falls back through: **ov** → **bat** → **man -l** → **less** → **cat**. diff --git a/docs/fish-config.md b/docs/fish-config.md index 844315a..8b69249 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -1179,6 +1179,8 @@ Add -i (interactive confirmation) to destructive commands: config-help --html config-help --man + Also available as: help config [SECTION] [FLAGS] + ### config-update Synopsis: config-update [-h] [-n] [-f] @@ -1600,7 +1602,7 @@ navigation. ## As a man page - config-help --man + help config --man Opens the compiled docs/fish-config.1 directly via man -l, bypassing the pager fallback chain. The symlink and MANPATH are also configured @@ -1614,7 +1616,7 @@ a completely separate command. Do not mix them up. ## In the browser (HTML) - config-help --html + help config --html Opens docs/html/index.html in the default web browser. Browser detection queries the system's x-scheme-handler/https MIME entry (via xdg-mime) to diff --git a/functions/config-help.fish b/functions/config-help.fish index d242d58..c829315 100644 --- a/functions/config-help.fish +++ b/functions/config-help.fish @@ -36,6 +36,11 @@ # config-help --html # config-help --man # config-help --help +# +# NOTES +# 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. function config-help --description 'Open the offline fish shell configuration manual' # ── --html / -w ────────────────────────────────────────────── if contains -- --html $argv; or contains -- -w $argv @@ -138,17 +143,17 @@ function config-help --description 'Open the offline fish shell configuration ma # ── --help / -h ────────────────────────────────────────────── if contains -- --help $argv; or contains -- -h $argv set_color --bold - echo config-help + echo "help config / 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)"--html"(set_color normal) - echo " config-help "(set_color yellow)"--man"(set_color normal) - echo " config-help "(set_color yellow)"--help"(set_color normal) + echo " help config "(set_color yellow)"[section]"(set_color normal) + echo " help config "(set_color yellow)"--html"(set_color normal) + echo " help config "(set_color yellow)"--man"(set_color normal) + echo " help config "(set_color yellow)"--help"(set_color normal) echo "" set_color --bold brblue echo ARGUMENTS @@ -163,13 +168,13 @@ 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 --html"(set_color normal)" open HTML docs in browser" - echo " "(set_color green)"config-help --man"(set_color normal)" open compiled man page" + echo " "(set_color green)"help config"(set_color normal)" open at top" + echo " "(set_color green)"help config keybindings"(set_color normal)" jump to Key Bindings section" + echo " "(set_color green)"help config pkg"(set_color normal)" jump to the pkg function entry" + echo " "(set_color green)"help config fish-deps"(set_color normal)" jump to fish-deps" + echo " "(set_color green)"help config abbreviations"(set_color normal)" jump to Abbreviations section" + echo " "(set_color green)"help config --html"(set_color normal)" open HTML docs in browser" + echo " "(set_color green)"help config --man"(set_color normal)" open compiled man page" echo "" set_color --bold brblue echo "NAVIGATION (ov pager)" diff --git a/functions/help.fish b/functions/help.fish index 32a5659..9cbe5d9 100644 --- a/functions/help.fish +++ b/functions/help.fish @@ -3,32 +3,60 @@ # SYNOPSIS # help [topic] [sub-topic...] +# help config [section] [-w|--html] [-m|--man] [-h|--help] # # 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 +# 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. # +# When the first argument is "config", the following flags are recognized +# and delegated to 'config-help': +# -w, --html Open the offline HTML docs in the default browser +# -m, --man Open the compiled man page via man -l +# -h, --help Print config-help usage reference +# +# Flags that appear WITHOUT a leading "config" argument — including -h/--help — +# are forwarded unchanged to the native Fish help command, so built-in +# behavior is never overridden for non-config topics. +# # ARGUMENTS -# topic Optional string representing the primary help subject (e.g., "config"). -# sub-topic Optional additional arguments passed exclusively to 'config-help'. +# topic Optional primary help subject (e.g., "config"). +# sub-topic Optional additional arguments passed to 'config-help'. +# section Keyword to jump to a section (only when topic is "config"). +# -w, --html Open HTML docs (only when topic is "config"). +# -m, --man Open man page (only when topic is "config"). +# -h, --help Print config-help usage (only when topic is "config"); +# otherwise forwarded to the native Fish 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 +# 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 config --html +# # Opens the offline HTML docs in the default browser +# +# help config keys --man +# # Opens the compiled man page via man -l +# +# help config --help +# # Prints the config-help usage reference +# # help string # # Forwards to the standard fish documentation for 'string' +# +# help --help +# # Forwards to the native Fish help command (not intercepted) # --- Initialization & Backup --- if not functions -q __original_help @@ -39,7 +67,10 @@ 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 + # All arguments after 'config' — including flags (-w/--html, -m/--man, + # -h/--help) and section keywords — are forwarded to config-help. + # Flags are only intercepted here when 'config' is the first argument, + # so native fish help flags are never shadowed for other topics. config-help $argv[2..] else __original_help $argv