Merge pull request #6444 from midchildan/feat/zsh-runhelp

feat: add integration with zsh's run-help

doc/manual/src/release-notes/rl-next.md

@@ -1,5 +1,10 @@
 # Release X.Y (202?-??-??)
 
+* Nix now provides better integration with zsh's run-help feature. It is now
+  included in the Nix installation in the form of an autoloadable shell
+  function, run-help-nix. It picks up Nix subcommands from the currently typed
+  in command and directs the user to the associated man pages.
+
 * `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
   while creating GC root symlinks.
 

misc/zsh/local.mk

@@ -1 +1,2 @@
 $(eval $(call install-file-as, $(d)/completion.zsh, $(datarootdir)/zsh/site-functions/_nix, 0644))
+$(eval $(call install-file-as, $(d)/run-help-nix, $(datarootdir)/zsh/site-functions/run-help-nix, 0644))

misc/zsh/run-help-nix

@@ -0,0 +1,42 @@
+emulate -L zsh
+
+# run-help is a zsh widget that can be bound to a key. It mainly looks up the
+# man page for the currently typed in command.
+#
+# Although run-help works for any command without requiring special support,
+# it can only deduce the right man page based solely on the name of the
+# command. Programs like Nix provide better integration with run-help by
+# helping zsh identify Nix subcommands and their corresponding man pages. This
+# is what this function does.
+#
+# To actually use run-help on zsh, place the following lines in your .zshrc:
+#
+#     (( $+aliases[run-help] )) && unalias run-help
+#     autoload -Uz run-help run-help-nix
+#
+# Then also assign run-help to any key of choice:
+#
+#     bindkey '^[h' run-help
+
+while [[ "$#" != 0 && "$1" == -* ]]; do
+  shift
+done
+
+local -a subcommands; subcommands=( nix3 )
+
+local arg
+for arg in "$@"; do
+  if man -w "${(j:-:)subcommands}-$arg" >/dev/null 2>&1; then
+    subcommands+="$arg"
+  else
+    break
+  fi
+done
+
+if (( $#subcommands > 1 )); then
+  man "${(j:-:)subcommands}"
+else
+  man nix
+fi
+
+return $?