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?

Solution 1

Other answers are too long...

Set up the run-help function by adding the following to your .zshrc:

unalias run-help
autoload run-help

Tip: Reload the config with . ~/.zshrc.

Now you should see a manual entry when you run run-help bindkey. If it doesn't work, you need to see more instructions for Accessing On-Line Help (man zshcontrib).

In some cases, run-help will not find a manual entry and you have to search through man zshall.

Solution 2

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.

Solution 3

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.

Solution 4

You can add those lines to your .zshrc profile:

unalias run-help 2>/dev/null
autoload run-help
HELPDIR=/path/to/zsh_help_directory
alias help=run-help

where /path/to/zsh_help_directory must be substituted by your zsh help folder. If you are on OS X with zsh installed via Homebrew, this folder is /usr/local/share/zsh/help

This will enable bash-like help for zsh.

It should be pointed out that if the default installation path of your zsh login shell's help files exists and contains the desired files, the third line HELPDIR=/path/to/zsh_help_directory won't be required.

Source your .zshrc ($ source .zshrc) and check that everything works fine with for instance (pick up any zsh builtin you want, here I picked autoload):

$ help autoload

Notice that the 2>/dev/null part is needed because without it, std error 'unalias: no such hash table element: run-help' would occur every time you source your .zshrc file while run-help is already unaliased.

Solution 5

I finally got sick of hunting through man pages and online searches each time I needed to get some Zsh info. I went through all of Zsh's man pages and put together a good "help" function that's fairly expansive.

To use this, I would create a file called "help" somewhere in your fpath and add autoload -Uz help to your zshrc.

# better help function than zsh's crappy run-help
local ZSHPAGE=zshall LESSQUERY
LESS="-RM~gIsw"
LESS_TERMCAP_mb=$'\E[01;31m'
LESS_TERMCAP_md=$'\E[01;31m'
LESS_TERMCAP_me=$'\E[0m'
LESS_TERMCAP_se=$'\E[0m'
LESS_TERMCAP_so=$'\E[01;44;33m'
LESS_TERMCAP_ue=$'\E[0m'
LESS_TERMCAP_us=$'\E[01;32m'

case "$@" in
    ""|--help|-h)
        local cmds='
RESERVED WORDS
do done esac then elif else fi for case if while function  repeat  time until  select  coproc nocorrect foreach end ! [[ { } declare export float integer local readonly typeset

BUILTIN COMMANDS
- . : [ [[ alias autoload bg bindkey break builtin bye cap cd chdir clone command comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues continue declare dirs disable disown echo echotc echoti emulate enable eval exec exit export false fc fg float functions getcap getln getopts hash history integer jobs kill lets limit local log logout noglob popd print printf pushd pushln pwd r read readonly rehash return sched set setcap setopt shift source stat suspend test times trap true ttyctl type typeset ulimit umask unalias unfunction unhash unlimit unset unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp
        '
        if whence -p fold >/dev/null; then
            fold -sw$COLUMNS <<< $cmds
        else
            print -- $cmds
        fi
        return;;
    '-- '*)
        shift
        LESSQUERY="$@";;
    loop*|while|do|done|if|then|elif|else|fi|until)
        LESSQUERY='^COMPLEX COMMANDS$'
        ZSHPAGE=zshmisc;;
    for)
        LESSQUERY='^       for name \.\.\. '
        ZSHPAGE=zshmisc;;
    foreach|end)
        LESSQUERY='^       foreach name \.\.\.'
        ZSHPAGE=zshmisc;;
    case|esac)
        LESSQUERY='^       case word'
        ZSHPAGE=zshmisc;;
    coproc)
        LESSQUERY='coproc'
        ZSHPAGE=zshmisc;;
    repeat)
        LESSQUERY='^       repeat word do'
        ZSHPAGE=zshmisc;;
    select)
        LESSQUERY='^       select name \[ in word'
        ZSHPAGE=zshmisc;;
    time)
        LESSQUERY='^       time \[ pipeline \]'
        ZSHPAGE=zshmisc;;
    list|'('*|'{'*|subshell)
        LESSQUERY='^       time \[ pipeline \]'
        ZSHPAGE=zshmisc;;
    '!'|not)
        LESSQUERY='^       \! exp  true if exp is false\.'
        ZSHPAGE=zshmisc;;
    .)
        LESSQUERY='^       \. file \[ arg \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    :)
        LESSQUERY='^       : \['
        ZSHPAGE=zshbuiltins;;
    alias)
        LESSQUERY='^       alias \['
        ZSHPAGE=zshbuiltins;;
    autoload)
        LESSQUERY='^       autoload \['
        ZSHPAGE=zshbuiltins;;
    *autoload*)
        LESSQUERY='^AUTOLOADING FUNCTIONS$'
        ZSHPAGE=zshmisc;;
    bg)
        LESSQUERY='^       bg \['
        ZSHPAGE=zshbuiltins;;
    bindkey)
        LESSQUERY='^ZLE BUILTINS$'
        ZSHPAGE=zshzle;;
    break)
        LESSQUERY='^       break \[ n \]'
        ZSHPAGE=zshbuiltins;;
    -|exec|command|noglob|nocorrect|builtin|precommand*)
        LESSQUERY='^PRECOMMAND MODIFIERS$'
        ZSHPAGE=zshmisc;;
    bye)
        LESSQUERY='^       bye    Same as exit\.'
        ZSHPAGE=zshbuiltins;;
    cap)
        LESSQUERY='^The zsh/cap Module$'
        ZSHPAGE=zshmodules;;
    cd)
        LESSQUERY='^       cd \[ -qsLP \] \[ arg \]'
        ZSHPAGE=zshbuiltins;;
    chdir)
        LESSQUERY='^       chdir  Same as cd\.'
        ZSHPAGE=zshbuiltins;;
    clone)
        LESSQUERY='^The zsh/clone Module'
        ZSHPAGE=zshmodules;;
    compargu*)
        LESSQUERY='^       comparguments$'
        ZSHPAGE=zshmodules;;
    compcall)
        LESSQUERY='^       compcall \[ -TD'
        ZSHPAGE=zshcompwid;;
    compctl)
        LESSQUERY='^       compctl \[ -CDT'
        ZSHPAGE=zshcompctl;;
    compdes*)
        LESSQUERY='^       compdescribe$'
        ZSHPAGE=zshmodules;;
    compfiles)
        LESSQUERY='^       compfiles$'
        ZSHPAGE=zshmodules;;
    compgroups)
        LESSQUERY='^       compgroups$'
        ZSHPAGE=zshmodules;;
    compquote)
        LESSQUERY='^       compquote$'
        ZSHPAGE=zshmodules;;
    comptags)
        LESSQUERY='^       comptags$'
        ZSHPAGE=zshmodules;;
    comptry)
        LESSQUERY='^       comptry$'
        ZSHPAGE=zshmodules;;
    compvalues)
        LESSQUERY='^       compvalues$'
        ZSHPAGE=zshmodules;;
    continue)
        LESSQUERY='^       continue \[ n \]'
        ZSHPAGE=zshbuiltins;;
    dirs)
        LESSQUERY='^       dirs \[ -c \]'
        ZSHPAGE=zshbuiltins;;
    disable)
        LESSQUERY='^       disable \[ -afmprs \]'
        ZSHPAGE=zshbuiltins;;
    disown)
        LESSQUERY='^       disown \[ job \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    echo)
        LESSQUERY='^       echo \[ -neE \]'
        ZSHPAGE=zshbuiltins;;
    echotc)
        LESSQUERY='^The zsh/termcap Module$'
        ZSHPAGE=zshmodules;;
    echoti)
        LESSQUERY='^The zsh/terminfo Module$'
        ZSHPAGE=zshmodules;;
    emulate)
        LESSQUERY='^       emulate \[ -LR \]'
        ZSHPAGE=zshbuiltins;;
    enable)
        LESSQUERY='^       enable \[ -afmprs \]'
        ZSHPAGE=zshbuiltins;;
    eval)
        LESSQUERY='^       eval \[ arg \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    exit)
        LESSQUERY='^       exit \[ n \]'
        ZSHPAGE=zshbuiltins;;
    export)
        LESSQUERY='^       export \[ name'
        ZSHPAGE=zshbuiltins;;
    fc)
        LESSQUERY='^       fc \[ -e ename \] \[ -LI \]'
        ZSHPAGE=zshbuiltins;;
    fg)
        LESSQUERY='^       fg \[ job \.\.\. \]S'
        ZSHPAGE=zshbuiltins;;
    functions)
        LESSQUERY='^       functions \[ \{\+\|-\}UkmtTuz'
        ZSHPAGE=zshbuiltins;;
    getcap)
        LESSQUERY='^The zsh/cap Module$'
        ZSHPAGE=zshmodules;;
    getln)
        LESSQUERY='^       getln \[ -AclneE \]'
        ZSHPAGE=zshbuiltins;;
    getopts)
        LESSQUERY='^       getopts optstring name'
        ZSHPAGE=zshbuiltins;;
    hash)
        LESSQUERY='^       hash \[ -Ldfmrv \]'
        ZSHPAGE=zshbuiltins;;
    history)
        LESSQUERY='^HISTORY EXPANSION$';;
    integer)
        LESSQUERY='^       integer \[ \{\+\|-\}Hghlprtux'
        ZSHPAGE=zshbuiltins;;
    jobs)
        LESSQUERY='^       jobs \[ -dlprs \]'
        ZSHPAGE=zshbuiltins;;
    kill)
        LESSQUERY='^       kill \[ -s signal_name'
        ZSHPAGE=zshbuiltins;;
    limit)
        LESSQUERY='^       limit \[ -hs \]'
        ZSHPAGE=zshbuiltins;;
    local)
        LESSQUERY='^       local \[ \{\+\|-\}AHUahlprtux '
        ZSHPAGE=zshbuiltins;;
    log)
        LESSQUERY='^       log    List all'
        ZSHPAGE=zshbuiltins;;
    logout)
        LESSQUERY='^       logout \[ n \]'
        ZSHPAGE=zshbuiltins;;
    popd)
        LESSQUERY='^       popd \[ -q \]'
        ZSHPAGE=zshbuiltins;;
    print)
        LESSQUERY='^       print \[ -abcDilmnNoOpPrsSz \]'
        ZSHPAGE=zshbuiltins;;
    printf)
        LESSQUERY='^       printf format \[ arg \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    pushd)
        LESSQUERY='^       pushd \[ -qsLP \]'
        ZSHPAGE=zshbuiltins;;
    pushln)
        LESSQUERY='^       pushln \[ arg \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    pwd)
        LESSQUERY='^       pwd \[ -rLP \]'
        ZSHPAGE=zshbuiltins;;
    r)
        LESSQUERY='^       r      Same as fc -e -\.'
        ZSHPAGE=zshbuiltins;;
    read)
        LESSQUERY='^       read \[ -rszpqAclneE \]'
        ZSHPAGE=zshbuiltins;;
    readonly)
        LESSQUERY='^       readonly$'
        ZSHPAGE=zshbuiltins;;
    rehash)
        LESSQUERY='^       rehash Same as hash -r\.'
        ZSHPAGE=zshbuiltins;;
    return)
        LESSQUERY='^       return \[ n \]'
        ZSHPAGE=zshbuiltins;;
    sched|'sched module')
        LESSQUERY='^THE ZSH/SCHED MODULE$'
        ZSHPAGE=zshmodules;;
    set)
        LESSQUERY='^       set \[ \{\+\|-\}options'
        ZSHPAGE=zshbuiltins;;
    setcap)
        LESSQUERY='^The zsh/cap Module$'
        ZSHPAGE=zshmodules;;
    setopt)
        LESSQUERY='^       setopt \[ \{\+\|-\}options'
        ZSHPAGE=zshbuiltins;;
    shift)
        LESSQUERY='^       shift \[ -p \]'
        ZSHPAGE=zshbuiltins;;
    source)
        LESSQUERY='^       source file \[ arg'
        ZSHPAGE=zshbuiltins;;
    stat|zstat|'stat module')
        LESSQUERY='^The zsh/stat Module$'
        ZSHPAGE=zshmodules;;
    times)
        LESSQUERY='^       times  Print'
        ZSHPAGE=zshbuiltins;;
    test|'[['*|'['*)
        LESSQUERY='^CONDITIONAL EXPRESSIONS$'
        ZSHPAGE=zshmisc;;
    trap)
        LESSQUERY='^       trap \[ arg \] \[ sig \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    true)
        LESSQUERY='^       true \[ arg \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    ttyctl)
        LESSQUERY='^       ttyctl \[ -fu \]'
        ZSHPAGE=zshbuiltins;;
    type)
        LESSQUERY='^       type \[ -wfpamsS \]'
        ZSHPAGE=zshbuiltins;;
    typeset|declare)
        LESSQUERY='^       typeset \[ \{\+\|-\}AHUaghlmprtux \]'
        ZSHPAGE=zshbuiltins;;
    ulimit)
        LESSQUERY='^       ulimit \[ -HSa \] \['
        ZSHPAGE=zshbuiltins;;
    umask)
        LESSQUERY='^       umask \[ -S \] \[ mask \]'
        ZSHPAGE=zshbuiltins;;
    unalias)
        LESSQUERY='^       unalias \[ -ams \]'
        ZSHPAGE=zshbuiltins;;
    unfunction)
        LESSQUERY='^       unfunction$'
        ZSHPAGE=zshbuiltins;;
    unhash)
        LESSQUERY='^       unhash \[ -adfms \]'
        ZSHPAGE=zshbuiltins;;
    unset)
        LESSQUERY='^       unset \[ -fmv \]'
        ZSHPAGE=zshbuiltins;;
    unsetopt)
        LESSQUERY='^       unsetopt \[ \{\+\|-\}options'
        ZSHPAGE=zshbuiltins;;
    vared)
        LESSQUERY='^       vared \[ -Aache \]'
        ZSHPAGE=zshzle;;
    wait)
        LESSQUERY='^       wait \[ job \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    whence)
        LESSQUERY='^       whence \[ -vcwfpamsS \]'
        ZSHPAGE=zshbuiltins;;
    where)
        LESSQUERY='^       where \[ -wpmsS \]'
        ZSHPAGE=zshbuiltins;;
    which)
        LESSQUERY='^       which \[ -wpamsS \]'
        ZSHPAGE=zshbuiltins;;
    zcompile)
        LESSQUERY='^       zcompile \[ -U \] \[ -z \|'
        ZSHPAGE=zshbuiltins;;
    zformat)
        LESSQUERY='^       zformat -f param format'
        ZSHPAGE=zshmodules;;
    zftp|'ftp module')
        LESSQUERY='^The zsh/zftp Module$'
        ZSHPAGE=zshmodules;;
    zle)
        LESSQUERY='^       zle -l \[ -L \| -a \] \[ string \.\.\. \]'
        ZSHPAGE=zshzle;;
    widget)
        LESSQUERY='^              widget \[ -n num \] \[ -Nw \]'
        ZSHPAGE=zshzle;;
    zmodload)
        LESSQUERY='^       zmodload \[ -dL \] \[ \.\.\. \]'
        ZSHPAGE=zshbuiltins;;
    zparseopts)
        LESSQUERY='^       zparseopts \[ -DKME \]'
        ZSHPAGE=zshmodules;;
    zprof|'zprof module')
        LESSQUERY='^THE ZSH/ZPROF MODULE$'
        ZSHPAGE=zshmodules;;
    zpty|'zpty module')
        LESSQUERY='^THE ZSH/ZPTY MODULE$'
        ZSHPAGE=zshmodules;;
    zregexparse)
        LESSQUERY='^       zregexparse$'
        ZSHPAGE=zshmodules;;
    zsocket|(net|socket)' module')
        LESSQUERY='^THE ZSH/NET/SOCKET MODULE$'
        ZSHPAGE=zshmodules;;
    zstyle|'zutil module')
        LESSQUERY='^The zsh/zutil Module$'
        ZSHPAGE=zshmodules;;
    ztcp|'tcp module')
        LESSQUERY='^THE ZSH/NET/TCP MODULE$'
        ZSHPAGE=zshmodules;;
    attr*mod*|zgetattr|zsetattr|zdelattr|zlistattr)
        LESSQUERY='^THE ZSH/ATTR MODULE$'
        ZSHPAGE=zshmodules;;
    complist*mod*)
        LESSQUERY='^THE ZSH/COMPLIST MODULE'
        ZSHPAGE=zshmodules;;
    computil*mod*)
        LESSQUERY='^THE ZSH/COMPUTIL MODULE'
        ZSHPAGE=zshmodules;;
    curses*|zcurses)
        LESSQUERY='^THE ZSH/CURSES MODULE'
        ZSHPAGE=zshmodules;;
    datetime*|strftime)
        LESSQUERY='^THE ZSH/DATETIME MODULE'
        ZSHPAGE=zshmodules;;
    (db|gdbm)*|ztie|zuntie)
        LESSQUERY='^THE ZSH/DB/GDBM MODULE'
        ZSHPAGE=zshmodules;;
    delto*|delete-to-char|zap-to-char)
        LESSQUERY='^THE ZSH/DELTOCHAR MODULE'
        ZSHPAGE=zshmodules;;
    example*)
        LESSQUERY='^THE ZSH/EXAMPLE MODULE'
        ZSHPAGE=zshmodules;;
    files*mod*|chgrp|chown|ln|mkdir|mv|rm|rmdir|sync)
        LESSQUERY='^THE ZSH/FILES MODULE'
        ZSHPAGE=zshmodules;;
    langinfo*)
        LESSQUERY='^THE ZSH/LANGINFO MODULE'
        ZSHPAGE=zshmodules;;
    mapfile*)
        LESSQUERY='^THE ZSH/MAPFILE MODULE'
        ZSHPAGE=zshmodules;;
    mathfunc*mod*)
        LESSQUERY='^THE ZSH/MATHFUNC MODULE'
        ZSHPAGE=zshmodules;;
    param*mod*)
        LESSQUERY='^THE ZSH/PARAMETER MODULE'
        ZSHPAGE=zshmodules;;
    pcre*)
        LESSQUERY='^THE ZSH/PCRE MODULE'
        ZSHPAGE=zshmodules;;
    regex*mod*)
        LESSQUERY='^THE ZSH/REGEX MODULE'
        ZSHPAGE=zshmodules;;
    system*mod*|syserror|sysopen|sysread|sysseek|syswrite|zsystem*)
        LESSQUERY='^THE ZSH/SYSTEM MODULE'
        ZSHPAGE=zshmodules;;
    zselect*)
        LESSQUERY='^THE ZSH/ZSELECT MODULE'
        ZSHPAGE=zshmodules;;
    start*flag*|invok*|initial*)
        LESSQUERY='^INVOCATION$'
        ZSHPAGE=zsh;;
    (start|shut)*file*|*zshenv|*zshrc|*zprofile|*zlogin|*zlogout|*zdotdir*|*ZDOTDIR*)
        LESSQUERY='^STARTUP/SHUTDOWN FILES$'
        ZSHPAGE=zsh;;
    subscript*)
        LESSQUERY='^   Subscript Flags'
        ZSHPAGE=zshparam;;
    simple*|pipe*)
        LESSQUERY='^SIMPLE COMMANDS & PIPELINES'
        ZSHPAGE=zshmisc;;
    function*)
        LESSQUERY='^       function word'
        ZSHPAGE=zshmisc;;
    alt*)
        LESSQUERY='^ALTERNATE FORMS$'
        ZSHPAGE=zshmisc;;
    reserv*)
        LESSQUERY='^RESERVED WORDS$'
        ZSHPAGE=zshmisc;;
    error*)
        LESSQUERY='^ERRORS$'
        ZSHPAGE=zshmisc;;
    alias*)
        LESSQUERY='^ALIASING$'
        ZSHPAGE=zshmisc;;
    quot*)
        LESSQUERY='^QUOTING$'
        ZSHPAGE=zshmisc;;
    redirect*|*'>'*|*'<'*|*'&>'*|*'2>'*|*'>>'*|*'<<'*)
        LESSQUERY='^REDIRECTION$'
        ZSHPAGE=zshmisc;;
    file*desc*)
        LESSQUERY='^OPENING FILE DESCRIPTORS USING PARAMETERS$'
        ZSHPAGE=zshmisc;;
    multios)
        LESSQUERY='^MULTIOS$'
        ZSHPAGE=zshmisc;;
    anon*func*)
        LESSQUERY='^ANONYMOUS FUNCTIONS$'
        ZSHPAGE=zshmisc;;
    hook*)
        LESSQUERY='^   Hook Functions$'
        ZSHPAGE=zshmisc;;
    trap*)
        LESSQUERY='^   Trap Functions$'
        ZSHPAGE=zshmisc;;
    job*)
        LESSQUERY='^JOBS$'
        ZSHPAGE=zshmisc;;
    math*|'(('*|'$(('|let*|arith*)
        LESSQUERY='^ARITHMETIC EVALUATION$'
        ZSHPAGE=zshmisc;;
    prompt|promptinit|prompt*theme*)
        LESSQUERY='^       prompt \[ -c \| -l \]'
        ZSHPAGE=zshcontrib;;
    PS1|prompt*|PROMPT*)
        LESSQUERY='^SIMPLE PROMPT ESCAPES$'
        ZSHPAGE=zshmisc;;
    history*)
        LESSQUERY='^HISTORY EXPANSION$'
        ZSHPAGE=zshexpn;;
    proc*sub*|*'<('*|*')>'*)
        LESSQUERY='^PROCESS SUBSTITUTION$'
        ZSHPAGE=zshexpn;;
    param*flag*)
        LESSQUERY='^   Parameter Expansion Flags$'
        ZSHPAGE=zshexpn;;
    param*rule*|nested*sub*)
        LESSQUERY='^   Rules$'
        ZSHPAGE=zshexpn;;
    param*ex*)
        LESSQUERY='^   Examples$'
        ZSHPAGE=zshexpn;;
    param*|'${')
        LESSQUERY='^PARAMETER EXPANSION$'
        ZSHPAGE=zshexpn;;
    brace*expan*)
        LESSQUERY='^BRACE EXPANSION$'
        ZSHPAGE=zshexpn;;
    filename*expan*)
        LESSQUERY='^FILENAME EXPANSION$'
        ZSHPAGE=zshexpn;;
    expan*|subst*)
        LESSQUERY='^       zshexpn - zsh expansion and substitution$'
        ZSHPAGE=zshexpn;;
    dyn*dir*)
        LESSQUERY='^   Dynamic named directories$'
        ZSHPAGE=zshexpn;;
    static*dir*)
        LESSQUERY='^   Static named directories$'
        ZSHPAGE=zshexpn;;
    approx*match*)
        LESSQUERY='^   Approximate Matching$'
        ZSHPAGE=zshexpn;;
    recurs*glob*)
        LESSQUERY='^   Recursive Globbing$'
        ZSHPAGE=zshexpn;;
    glob*qual*)
        LESSQUERY='^   Glob Qualifiers$'
        ZSHPAGE=zshexpn;;
    glob*flag*)
        LESSQUERY='^   Globbing Flags$'
        ZSHPAGE=zshexpn;;
    glob*)
        LESSQUERY='^   Glob Operators$'
        ZSHPAGE=zshexpn;;
    ksh*glob*)
        LESSQUERY='^   ksh-like Glob Operators'
        ZSHPAGE=zshexpn;;
    array*sub*)
        LESSQUERY='^   Array Subscripts$'
        ZSHPAGE=zshparam;;
    array*)
        LESSQUERY='^ARRAY PARAMETERS$'
        ZSHPAGE=zshparam;;
    positional*)
        LESSQUERY='^POSITIONAL PARAMETERS$'
        ZSHPAGE=zshparam;;
    shell*(param*|var*)|env*)
        LESSQUERY='^PARAMETERS SET BY THE SHELL$'
        ZSHPAGE=zshparam;;
    watchfmt*)
        LESSQUERY='^       WATCHFMT$'
        ZSHPAGE=zshparam;;
    set*|(shell|spec)*op*)
        LESSQUERY='^SPECIFYING OPTIONS$'
        ZSHPAGE=zshoptions;;
    single*opt*|short*flag*|single*letter*)
        LESSQUERY='^SINGLE LETTER OPTIONS$'
        ZSHPAGE=zshoptions;;
    (shell|zsh)*builtin*)
        LESSQUERY='^SHELL BUILTIN COMMANDS$'
        ZSHPAGE=zshbuiltins;;
    key*)
        LESSQUERY='^KEYMAPS$'
        ZSHPAGE=zshzle;;
    widget*)
        LESSQUERY='^USER-DEFINED WIDGETS$'
        ZSHPAGE=zshzle;;
    highlight*)
        LESSQUERY='^CHARACTER HIGHLIGHTING$'
        ZSHPAGE=zshzle;;
    comp*wid*)
        LESSQUERY='^       zshcompwid - zsh completion widgets'
        ZSHPAGE=zshcompwid;;
    complet*param*|*PREFIX*|*CURRENT*|*SUFFIX*)
        LESSQUERY='^COMPLETION SPECIAL PARAMETERS$'
        ZSHPAGE=zshcompwid;;
    compstate)
        LESSQUERY='^       compstate$'
        ZSHPAGE=zshcompwid;;
    compadd)
        LESSQUERY='^       compadd \[ -akqQfenUlo12C '
        ZSHPAGE=zshcompwid;;
    compset)
        LESSQUERY='^       compset -p number'
        ZSHPAGE=zshcompwid;;
    compcall)
        LESSQUERY='^       compcall \[ -TD'
        ZSHPAGE=zshcompwid;;
    *match*)
        LESSQUERY='^COMPLETION MATCHING CONTROL$'
        ZSHPAGE=zshcompwid;;
    *compsys*)
        LESSQUERY='^       zshcompsys - zsh completion system'
        ZSHPAGE=zshcompsys;;
    compdef*)
        LESSQUERY='^       compdef \[ -ane \]'
        ZSHPAGE=zshcompsys;;
    '#'compdef*)
        LESSQUERY='^       #compdef name'
        ZSHPAGE=zshcompsys;;
    *completer*)
        LESSQUERY='^       completer$'
        ZSHPAGE=zshcompsys;;
    *complet*|*'zstyle '*)
        LESSQUERY='^COMPLETION SYSTEM CONFIGURATION$'
        ZSHPAGE=zshcompsys;;
    utility*func*|_argu*|_descr*)
        LESSQUERY='^UTILITY FUNCTIONS$'
        ZSHPAGE=zshcompsys;;
    control*func*|_func*)
        LESSQUERY='^CONTROL FUNCTIONS$'
        ZSHPAGE=zshcompsys;;
    calendar*)
        LESSQUERY='^       calendar \[ -abdDsv'
        ZSHPAGE=zshcalsys;;
    calsys*)
        LESSQUERY='^       zshcalsys - zsh calendar system'
        ZSHPAGE=zshcalsys;;
    tcp*)
        LESSQUERY='^       zshtcpsys - zsh tcp system'
        ZSHPAGE=zshtcpsys;;
    ftp*|zftp*)
        LESSQUERY='^       zshzftpsys - zftp function front-end'
        ZSHPAGE=zshzftpsys;;
    contrib*)
        LESSQUERY='^       zshcontrib - user contributions to zsh'
        ZSHPAGE=zshcontrib;;
    special*func*)
        LESSQUERY='^SPECIAL FUNCTIONS'
        ZSHPAGE=zshmisc;;
    color*comp*)
        LESSQUERY='^   Colored completion listings'
        ZSHPAGE=zshmodules;;
    colors)
        LESSQUERY='^       colors This  function'
        ZSHPAGE=zshcontrib;;
    vcs*|version*control*)
        LESSQUERY='^GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS$'
        ZSHPAGE=zshcontrib;;
    zle*)
        LESSQUERY='^ZLE FUNCTIONS$'
        ZSHPAGE=zshzle;;
    mime*)
        LESSQUERY='^MIME FUNCTIONS$'
        ZSHPAGE=zshcontrib;;
    zcalc*)
        LESSQUERY='^       zcalc \[ -ef'
        ZSHPAGE=zshcontrib;;
    zmathfuncdef)
        LESSQUERY='^       zmathfuncdef \['
        ZSHPAGE=zshcontrib;;
    other*func*)
        LESSQUERY='^OTHER FUNCTIONS'
        ZSHPAGE=zshcontrib;;
    zargs)
        LESSQUERY='       zargs \[ option'
        ZSHPAGE=zshcontrib;;
    tetris*)
        LESSQUERY='^       tetris Zsh'
        ZSHPAGE=zshcontrib;;
    zed)
        LESSQUERY='^       zed \[ -f'
        ZSHPAGE=zshcontrib;;
    zmv|zcp|zln|zkbd)
        LESSQUERY='^       zmv \[ -finq'
        ZSHPAGE=zshcontrib;;
    zstyle+)
        LESSQUERY='^       zstyle\+ context'
        ZSHPAGE=zshcontrib;;
    file*)
        LESSQUERY='^FILES$'
        ZSHPAGE=zsh;;
    except*|throw|catch|always)
        LESSQUERY='^EXCEPTION HANDLING$'
        ZSHPAGE=zshcontrib;;
    *)
        LESSQUERY="$@";;
esac
man --pager="less -p'$LESSQUERY'" "$ZSHPAGE"

It uses less as the pager and enables less's termcap support for color man pages. Executing help with no parameters or --help or -h lists reserved words and builtin commands. Typing help with one of those words brings you right to the entry in the appropriate man page. I went through and narrowed down entries in specific man pages to optimize for speed/efficiency, as opposed to just using man ... zshall. This help function finds a lot more than just reserved words and builtin commands. It will locate entries for modules, module commands, certain important completion commands such as compadd, compset, etc.

Many sections on things like arithmetic, completion, globbing, arrays, environment variables, exception handling are shown by typing help math, help complet, help glob, help arrays, help env, help except. There are wildcards and multiple match terms to make the help function more friendly. It's a fairly simple case statement with a little over 210 matching conditions. If nothing's matched it defaults to a zshall search. If the matching conditions don't show what you're looking for or seem to get in the way, type help -- following by your search terms to bypass all matching.

I included a lot of what the Zsh man pages cover, but it could be made smarter or more complete by including things like the underscore prefixed completion functions.

---

edit: I made a bindkey function for ^[h (esc/alt + h). run-help is bound there by default, and this replaces it.

_helpprefix(){
    OLDBUFFER="$BUFFER"
    zle backward-kill-word
    BUFFER="help $CUTBUFFER"
    zle accept-line
    zle -U "$OLDBUFFER"
}
zle -N _helpprefix _helpprefix
bindkey '^[h' _helpprefix

What this does is cut out the last word typed, execute help with that word and then it pushes back in the original line. So you can use it to run help on read in a command like this:

find /usr -print0 | while IFS= read

You'll still be right at the end of your command after viewing the entry for read.

Also something worth noting, if you ever need help with flags for a particular builtin, you can always add a - after the command and hit tab to see short descriptions of each flag, e.g. read - + tab prints this out:

-A  -- first name is taken as an array
-E  -- input read is echoed
-d  -- specify delimiter to terminate input instead of newline
-e  -- input read is echoed and not assigned
-k  -- specify number of characters to read
-q  -- read y or n character from terminal
-r  -- raw mode
-s  -- suppress terminal echoing
-t  -- test if input is available before reading
-u  -- specify file descriptor to read from
-z  -- read entry from editor buffer stack

View more solutions

Comments

[jcomeau_ictx]

but as my system doesn't have 'bindkey', not sure if this answer helps or not.

[John Bachir]

no mention of bindkey or alias (a random common one i picked) in the zsh man page

[John Bachir]

Sweet! Have a link to the zsh distribution described in that howto?

[ches]

Not sure what you mean -- the zsh-4.3.12/Util/helpfiles script it refers to? Just find your installed zsh version with zsh --version and then grab the corresponding source tarball from the sourceforge archive. Once you've finished with the steps you can delete the source you downloaded and extracted if you like. Let me know if that's not what you were asking!

[xuhdev]

Good news is that the latest snapshot version has added the generation of the helpfiles during configuration. Probably it will be available in 5.0.3. See here.

[Coren]

For those of you using vi-mode ESC-h doesn't work as described above. You can type ESC to enter command mode and then :run-help. Alternatively, you can add alias help=run-help to your .zshrc (or wherever you keep your aliases).

[anol]

Has this changed recently? My zsh (5.0.2) does not have any associated man pages (the autocompletion only suggests zsh5, and trying man zsh5 results in: man: warning: /usr/share/man/man1/zsh5.1.gz is a dangling symlink). I had to install the Ubuntu package zsh-doc to be able to do info zsh, then go to the Builtins section to finally obtain information about echo.

[SourceSeeker]

@anol: Apparently it's a bug in 13.10 and 14.04, but it's back in place in 14.10. You can install them from source (information at the link) or view them online (e.g. here).

[jcomeau_ictx]

downvoters: please note that the original post made no mention of zsh, just "shell".

[ches]

@ntc2 Your edit seems incomplete—the "before 5.0.3" section now starts with a nonsensical sentence fragment.

[ntc2]

@ches: sorry about that. It's fixed now.

[John Bachir]

This works great. What is the way that zsh "expects" us to access these help documents? Why do we have to unalias run-help, autoload it again, and then tell it where the docs are?

[John Bachir]

This actually doesn't work for me in zsh 5.0.5 on os x (using the zsh that comes with os x). I have to take the steps described in this answer: stackoverflow.com/a/35456287/168143 -- anyone know why?

[John Bachir]

Also I would vote for removing the alias help=run-help bit, to make a more minimal answer.

[John Bachir]

For anyone using the default os x zsh, the help path is /usr/share/zsh/5.0.5/help

[ches]

@JohnBachir Confirmed in the same environment/version. Unsure what to do here because the part "For ZSH version 5.0.3 or newer" was an edit that was not my own, thus probably should have been a new answer. I'd like to re-edit to correct that once I can try to confirm the behavior in another environment, but don't want to take credit for lendenmc's answer. I suppose at worst I'll just remove that section if I can't validate it.

[ches]

Also, using the default system installation on OS X, it appears that it isn't necessary to set HELPDIR explicitly at all. Works for me without that step.

[ches]

Sorry, actually the behavior is different with HELPDIR set vs. not—without it it often directly opens the relevant man page, while with it it references the more targeted information extracted by the tools (or sometimes less helpfully just tells you to open a man page…). By the way @JohnBachir man zshcontrib again sheds light on the expected usage. I'm guessing packaging the extracted help info is a distribution-specific choice so they default to the man alias.

[ches]

Okay so everything in the answer is still basically correct, just slightly but critically incomplete without highlighting the need for the run-help alias switcheroo. In short, the man page still provides an authoritative answer. I'll make an edit to the effect of saying that.

[lendenmc]

@JohnBachir, run-help is not really 're-autoloaded' ('autoload it again' as you put it). As explained in @ches's answer, run-help is only an alias for the man command at first. So once this alias is removed, then you need to autoload the run-help function for the first time in order to be able to use it.... if that makes sense.

[CMCDragonkai]

This is pretty cool, but is there any way to make automatically select where the help files are. Specifically /usr/share/zsh/${VERSION}/help, why isn't there already a variable defined for where these help files are?

[lendenmc]

@CMCDragonkai, according to the doc "The HELPDIR parameter tells run-help where to look for the help files. When unset, it uses the default installation path". However, on some platforms such as OS X El Capitan, the default zsh is outdated and points to an installation path that doesn't exit. So in this case, if you don't want to change the default zsh but wants run-help to be able access help files, you'll need to specify a location with HELPDIR. If the default installation path exists and contains the desired help files, then you won't need that line.

[jsears]

If using the homebrew version of zsh on osx, use: HELPDIR="/usr/local/share/zsh/help"

[jsears]

If using the homebrew version of zsh on osx, use: HELPDIR="/usr/local/share/zsh/help"

[John P]

This might only be tangentially related, but at least if I'm experimenting, I go out of my way not to suppress stderr. In this case I would use something like alias run-help >/dev/null (suppressing stdout of a read) to suppress only the errors I accounted for. Aliases could have already poisoned the well, so to speak.

[Sridhar Sarnobat]

Arghhhhh, why can't I get run-help history to work for the history command? Like the OP said this is frustrating.

[cambunctious]

@SridharSarnobat When I run run-help history I see docs for fc. Scroll to the bottom and it says history: Same as fc -l.

[uchuugaka]

No, the explanations are very valuable.

[uchuugaka]

FWIW, on macOS 10.15 and up run-help seems to work out-of-the-box … ¯_(ツ)_/¯

[David J.]

I was wondering: is the unalias run-help always necessary? Perhaps not, but it is probably smarter and safer, because on my system (at least, and probably many others) run-help is aliased to run-help=man. So unaliasing it first is essential in some cases. Since unaliasing doesn't hurt here, I see why including it is a good idea.

[cambunctious]

@uchuugaka By default run-help is aliased to man which is not the same. Run which run-help to check.