How can I read documentation about built in zsh commands?

Question

It's frustrating when I do something like man bindkey and i get:

BUILTIN(1)                BSD General Commands Manual               BUILTIN(1)

NAME
     builtin, !, %, ., :, @, {, }, alias, alloc, bg, bind, bindkey, break, breaksw, builtins, case, cd, chdir, command,
     complete, continue, default, dirs, do, done, echo, echotc, elif, else, end, endif, endsw, esac, eval, exec, exit,
     export, false, fc, fg, filetest, fi, for, foreach, getopts, glob, goto, hash, hashstat, history, hup, if, jobid,
     jobs, kill, limit, local, log, login, logout, ls-F, nice, nohup, notify, onintr, popd, printenv, pushd, pwd, read,
     readonly, rehash, repeat, return, sched, set, setenv, settc, setty, setvar, shift, source, stop, suspend, switch,
     telltc, test, then, time, times, trap, true, type, ulimit, umask, unalias, uncomplete, unhash, unlimit, unset,
     unsetenv, until, wait, where, which, while -- shell built-in commands

SYNOPSIS
     builtin [-options] [args ...]

DESCRIPTION
     Shell builtin commands are commands that can be executed within the running shell's process.  Note that, in the

Is there an easy way to access the documentation for such commands?

Answer 1

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 the man command, so this often fails when the command word is a shell builtin or a user-defined function. By redefining the run-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.