How can I read documentation about built in zsh commands?
Try either of these:
man zshbuiltins
or
man zshall
The man pages for zsh are divided up by topic, man zsh
is mostly a table of contents and introduction while man zshall
is everything (24628 lines on my system compared to 5242 for man bash
).
As for bindkey
, man zshbuiltins
will refer you to man zshzle
.
The key information for getting a more useful help utility is actually included with Zsh, it's just a matter of finding the critical—and poorly discoverable—man page: man zshcontrib
(here on the web), which describes the run-help
widget:
By default,
run-help
is an alias for theman
command, so this often fails when the command word is a shell builtin or a user-defined function. By redefining therun-help
alias, one can improve the on-line help provided by the shell.
It further explains how to replace it with a built-in improvement.
After setting this up, calling run-help
for names of builtins, completion functions and so forth will now try to show you extracted documentation, or show you the right containing man page, etc. For example run-help bindkey
outputs:
bindkey
See the section `Zle Builtins' in zshzle(1).
which could be better. For a better example, run-help history
shows the Zsh man page section for fc
, which is the command that underlies history
.
Also handy to note: ESC-h
will call run-help
for the command on the current input line.
I presume this setup isn't the default because extracting the granular help data and setting HELPDIR
to point to it might be a packaging decision left to OS distributions. There's also a user choice: the autoload run-help
util is useful without setting HELPDIR
at all. It seems to be good at taking you to the right man page even if it can't jump to the exact section for one item. Some may prefer this to running into cases like the bindkey
example above which just wastes time. (Why they default to alias run-help=man
then, I cannot fathom).
For Zsh version 5.0.3 or newer
The helpfiles
extractions are likely included with the Zsh distribution. It's just a matter of finding them on your system to set HELPDIR
if you wish—likely candidates are in /usr/share/zsh
or /usr/local/share/zsh
, look for a help
subdirectory.
For versions of Zsh before 5.0.3
You will likely need to follow the procedure detailed in man zshcontrib
yourself to generate the help files. It's a little annoying to need to do this, but otherwise quick and painless.
Find your installed version with zsh --version
and obtain the corresponding source tarball from the sourceforge archive. Then run the helpfiles
script as shown in the man page and set the target as HELPDIR
in your ~/.zshrc
.