rootiest/fish-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(help): prefer help config syntax; add NOTES to config-help doc block
Generate documentation / build-docs (push) Successful in 35s
Details
Offline docs drift reminder / remind (push) Successful in 10s
Details

Browse Source 
- help.fish: expand SYNOPSIS/DESCRIPTION to document -w/--html, -m/--man,
  -h/--help flags; note flags are only intercepted when 'config' is argv[1]
- config-help.fish: add # NOTES section explaining help config as the
  preferred invocation; update --help banner to show both names; update
  --help USAGE/EXAMPLES output to use `help config` syntax throughout
- docs/fish-config.md: update §5.14 synopsis/examples and "Viewing" sections
  to use `help config` as primary form; inline note for direct config-help use
- README.md: update docs table to show `help config --html` / `--man`
This commit is contained in:
Rootiest
2026-06-08 23:04:39 -04:00
parent e86b537f6d
commit 79f8445e25
4 changed files with 62 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -45,8 +45,8 @@ To browse the docs from the terminal:
|---|---|
| `help config` | Open the terminal manual in the best available pager |
| `help config <keyword>` | 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**.
docs/fish-config.md
+4 -2
View File
@@ -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
functions/config-help.fish
+17 -12
View File
@@ -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)"
functions/help.fish
+39 -8
View File
@@ -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