diff --git a/conf.d/help.fish b/conf.d/help.fish new file mode 100644 index 0000000..ecca847 --- /dev/null +++ b/conf.d/help.fish @@ -0,0 +1,67 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later +# +# ╭──────────────────────────────────────────────────────────╮ +# │ help config wrapper │ +# ╰──────────────────────────────────────────────────────────╯ +# +# 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 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. +# +# NOTES +# To prevent infinite recursion, the wrapper backs up the native help +# function as '__original_help' before shadowing it. This MUST happen from +# conf.d, not functions/help.fish: as of Fish 4.x the native help is +# embedded in the binary (embedded:functions/help.fish) with no on-disk +# file to source, and a functions/help.fish autoload shadow makes the name +# 'help' resolve to our own wrapper (or nothing, mid-autoload) — so the +# backup could never capture the real help. Sourced here at startup, before +# any shadow exists, `functions -c help` copies the embedded original. +# +# EXAMPLE +# help config keys # → config-help keys +# help config --html # opens the offline HTML docs in the browser +# help config keys --man # opens the compiled man page via man -l +# help string # forwards to native fish docs for 'string' + +# --- Initialization & Backup --- +# Copy the native (embedded) help to __original_help before we shadow it. +if not functions -q __original_help + functions -c help __original_help +end + +# --- Wrapper Definition --- +function help --wraps help --description "Custom wrapper to intercept 'help config'" + # Opinionated guard (C1): fall back to the native fish help when disabled. + if not __fish_config_op_enabled __fish_config_op_aliases + __original_help $argv + return $status + end + + if test "$argv[1]" = config + # 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 + end +end diff --git a/functions/help.fish b/functions/help.fish deleted file mode 100644 index 2111ee7..0000000 --- a/functions/help.fish +++ /dev/null @@ -1,84 +0,0 @@ -# Copyright (C) 2026 Rootiest -# SPDX-License-Identifier: AGPL-3.0-or-later - -# 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 -# 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 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 -# 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 - 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'" - # Opinionated guard (C1): fall back to the native fish help when disabled. - if not __fish_config_op_enabled __fish_config_op_aliases - __original_help $argv - return $status - end - - if test "$argv[1]" = config - # 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 - end -end