From a642cc3274548b1f918555bb9ac776bc01c0f556 Mon Sep 17 00:00:00 2001
From: Peter Stephenson <pws@users.sourceforge.net>
Date: Thu, 15 Nov 2001 15:54:09 +0000
Subject: 15288, 15432, 15585: Zle widgets with bash-style word delimiting

---
 Doc/Zsh/contrib.yo | 930 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 930 insertions(+)
 create mode 100644 Doc/Zsh/contrib.yo

(limited to 'Doc')

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
new file mode 100644
index 000000000..1c42fccb8
--- /dev/null
+++ b/Doc/Zsh/contrib.yo
@@ -0,0 +1,930 @@
+texinode(User Contributions)()(Zftp Function System)(Top)
+chapter(User Contributions)
+cindex(user contributions)
+sect(Description)
+
+The Zsh source distribution includes a number of items contributed by the
+user community.  These are not inherently a part of the shell, and some
+may not be available in every zsh installation.  The most significant of
+these are documented here.  For documentation on other contributed items
+such as shell functions, look for comments in the function source files.
+
+startmenu()
+menu(Utilities)
+menu(Prompt Themes)
+menu(ZLE Functions)
+menu(Other Functions)
+endmenu()
+
+texinode(Utilities)(Prompt Themes)()(User Contributions)
+sect(Utilities)
+
+subsect(Accessing On-Line Help)
+cindex(helpfiles utility)
+
+The key sequence tt(ESC h) is normally bound by ZLE to execute the
+tt(run-help) widget (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+).  This invokes the tt(run-help) command with the command word from the
+current input line as its argument.  By default, tt(run-help) is an alias
+for the tt(man) command, so this often fails when the command word is a
+shell builtin or a user-defined function.  By redefining the tt(run-help)
+alias, one can improve the on-line help provided by the shell.
+
+The tt(helpfiles) utility, found in the tt(Util) directory of the
+distribution, is a Perl program that can be used to process the zsh manual
+to produce a separate help file for each shell builtin and for many other
+shell features as well.  The autoloadable tt(run-help) function, found in
+tt(Functions/Misc), searches for these helpfiles and performs several
+other tests to produce the most complete help possible for the command.
+
+There may already be a directory of help files on your system; look in
+tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below
+those, or ask your system administrator.
+
+To create your own help files with tt(helpfiles), choose or create a
+directory where the individual command help files will reside.  For
+example, you might choose tt(~/zsh_help).  If you unpacked the zsh
+distribution in your home directory, you would use the commands:
+
+example(mkdir ~/zsh_help
+cd ~/zsh_help
+man zshall | colcrt - | \ 
+perl ~/zsh-version()/Util/helpfiles)
+
+findex(run-help, use of)
+Next, to use the tt(run-help) function, you need to add lines something
+like the following to your tt(.zshrc) or equivalent startup file:
+
+example(unalias run-help
+autoload run-help
+HELPDIR=~/zsh_help)
+
+vindex(HELPDIR)
+The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
+files.  If your system already has a help file directory installed, set
+tt(HELPDIR) to the path of that directory instead.
+
+Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
+file must be in one of the directories named in your tt(fpath) array (see
+ifzman(zmanref(zshparam))\
+ifnzman(noderef(Parameters Used By The Shell))\
+).  This should already be the case if you have a standard zsh
+installation; if it is not, copy tt(Functions/Misc/run-help) to an
+appropriate directory.
+
+subsect(Recompiling Functions)
+cindex(functions, recompiling)
+cindex(zrecompile utility)
+
+If you frequently edit your zsh functions, or periodically update your zsh
+installation to track the latest developments, you may find that function
+digests compiled with the tt(zcompile) builtin are frequently out of date
+with respect to the function source files.  This is not usually a problem,
+because zsh always looks for the newest file when loading a function, but
+it may cause slower shell startup and function loading.  Also, if a digest
+file is explicitly used as an element of tt(fpath), zsh won't check whether
+any of its source files has changed.
+
+The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), can
+be used to keep function digests up to date.
+
+startitem()
+findex(zrecompile)
+xitem(tt(zrecompile) [ tt(-qt) ] [ var(name) ... ])
+item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(args) [ tt(-)tt(-) var(args) ... ])(
+This tries to find tt(*.zwc) files and automatically re-compile them if at
+least one of the original files is newer than the compiled file.  This
+works only if the names stored in the compiled files are full paths or are
+relative to the directory that contains the tt(.zwc) file.
+
+In the first form, each var(name) is the name of a compiled file or a
+directory containing tt(*.zwc) files that should be checked.  If no
+arguments are given, the directories and tt(*.zwc) files in tt(fpath) are
+used.
+
+When tt(-t) is given, no compilation is performed, but a return status of
+zero (true) is set if there are files that need to be re-compiled and
+non-zero (false) otherwise.  The tt(-q) option quiets the chatty output
+that describes what tt(zrecompile) is doing.
+
+Without the tt(-t) option, the return status is zero if all files that
+needed re-compilation could be compiled and non-zero if compilation for at
+least one of the files failed.
+
+If the tt(-p) option is given, the var(args) are interpreted as one
+or more sets of arguments for tt(zcompile), separated by `tt(-)tt(-)'.
+For example:
+
+example(zrecompile -p \ 
+           -R ~/.zshrc -- \ 
+           -M ~/.zcompdump -- \ 
+           ~/zsh/comp.zwc ~/zsh/Completion/*/_*)
+
+This compiles tt(~/.zshrc) into tt(~/.zshrc.zwc) if that doesn't exist or
+if it is older than tt(~/.zshrc). The compiled file will be marked for
+reading instead of mapping. The same is done for tt(~/.zcompdump) and
+tt(~/.zcompdump.zwc), but this compiled file is marked for mapping. The
+last line re-creates the file tt(~/zsh/comp.zwc) if any of the files
+matching the given pattern is newer than it.
+
+Without the tt(-p) option, tt(zrecompile) does not create function digests
+that do not already exist, nor does it add new functions to the digest.
+)
+enditem()
+
+The following shell loop is an example of a method for creating function
+digests for all functions in your tt(fpath), assuming that you have write
+permission to the directories:
+
+example(for ((i=1; i <= $#fpath; ++i)); do
+  dir=$fpath[i]
+  zwc=${dir:t}.zwc
+  if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
+    continue
+  fi
+  files=($dir/*(N-.))
+  if [[ -w $dir:h && -n $files ]]; then
+    files=(${${(M)files%/*/*}#/})
+    if ( cd $dir:h &&
+         zrecompile -p -U -z $zwc $files ); then
+      fpath[i]=$fpath[i].zwc
+    fi
+  fi
+done)
+
+The tt(-U) and tt(-z) options are appropriate for functions in the default
+zsh installation tt(fpath); you may need to use different options for your
+personal function directories.
+
+Once the digests have been created and your tt(fpath) modified to refer to
+them, you can keep them up to date by running tt(zrecompile) with no
+arguments.
+
+subsect(Keyboard Definition)
+cindex(keyboard definition)
+
+findex(zkbd)
+The large number of possible combinations of keyboards, workstations,
+terminals, emulators, and window systems makes it impossible for zsh to
+have built-in key bindings for every situation.  The tt(zkbd) utility,
+found in Functions/Misc, can help you quickly create key bindings for your
+configuration.
+
+Run tt(zkbd) either as an autoloaded function, or as a shell script:
+
+example(zsh -f ~/zsh-version()/Functions/Misc/zkbd)
+
+When you run tt(zkbd), it first asks you to enter your terminal type; if
+the default it offers is correct, just press return.  It then asks you to
+press a number of different keys to determine characteristics of your
+keyboard and terminal; tt(zkbd) warns you if it finds anything out of the
+ordinary, such as a Delete key that sends neither tt(^H) nor tt(^?).
+
+The keystrokes read by tt(zkbd) are recorded as a definition for an
+associative array named tt(key), written to a file in the subdirectory
+tt(.zkbd) within either your tt(HOME) or tt(ZDOTDIR) directory.  The name
+of the file is composed from the tt(TERM), tt(VENDOR) and tt(OSTYPE)
+parameters, joined by hyphens.
+
+You may read this file into your tt(.zshrc) or another startup file with
+the "source" or "." commands, then reference the tt(key) parameter in
+bindkey commands, like this:
+
+example(source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
+[[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
+[[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
+# etc.)
+
+Note that in order for `tt(autoload zkbd)' to work, the tt(zkdb) file must
+be in one of the directories named in your tt(fpath) array (see
+ifzman(zmanref(zshparam))\
+ifnzman(noderef(Parameters Used By The Shell))\
+).  This should already be the case if you have a standard zsh
+installation; if it is not, copy tt(Functions/Misc/zkbd) to an
+appropriate directory.
+
+subsect(Dumping Shell State)
+cindex(reporter utility)
+
+Occasionally you may encounter what appears to be a bug in the shell,
+particularly if you are using a beta version of zsh or a development
+release.  Usually it is sufficient to send a description of the
+problem to one of the zsh mailing lists (see
+ifzman(zmanref(zsh))\
+ifnzman(noderef(Mailing Lists))\
+), but sometimes one of the zsh developers will need to recreate your
+environment in order to track the problem down.
+
+The script named tt(reporter), found in the tt(Util) directory of the
+distribution, is provided for this purpose.  (It is also possible to
+tt(autoload reporter), but tt(reporter) is not installed in tt(fpath)
+by default.)  This script outputs a detailed dump of the shell state,
+in the form of another script that can be read with `tt(zsh -f)' to
+recreate that state.
+
+To use tt(reporter), read the script into your shell with the `tt(.)'
+command and redirect the output into a file:
+
+example(. ~/zsh-version()/Util/reporter > zsh.report)
+
+You should check the tt(zsh.report) file for any sensitive information
+such as passwords and delete them by hand before sending the script to the
+developers.  Also, as the output can be voluminous, it's best to wait for
+the developers to ask for this information before sending it.
+
+You can also use tt(reporter) to dump only a subset of the shell state.
+This is sometimes useful for creating startup files for the first time.
+Most of the output from reporter is far more detailed than usually is
+necessary for a startup file, but the tt(aliases), tt(options), and
+tt(zstyles) states may be useful because they include only changes from
+the defaults.  The tt(bindings) state may be useful if you have created
+any of your own keymaps, because tt(reporter) arranges to dump the keymap
+creation commands as well as the bindings for every keymap.
+
+As is usual with automated tools, if you create a startup file with
+tt(reporter), you should edit the results to remove unnecessary commands.
+Note that if you're using the new completion system, you should em(not)
+dump the tt(functions) state to your startup files with tt(reporter); use
+the tt(compdump) function instead (see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+).
+
+startitem()
+item(tt(reporter) [ var(state) ... ])(
+findex(reporter)
+Print to standard output the indicated subset of the current shell state.
+The var(state) arguments may be one or more of:
+
+startsitem()
+sitem(tt(all))(Output everything listed below.)
+sitem(tt(aliases))(Output alias definitions.)
+sitem(tt(bindings))(Output ZLE key maps and bindings.)
+sitem(tt(completion))(Output old-style tt(compctl) commands.
+New completion is covered by tt(functions) and tt(zstyles).)
+sitem(tt(functions))(Output autoloads and function definitions.)
+sitem(tt(limits))(Output tt(limit) commands.)
+sitem(tt(options))(Output tt(setopt) commands.)
+sitem(tt(styles))(Same as tt(zstyles).)
+sitem(tt(variables))(Output shell parameter assignments, plus tt(export)
+commands for any environment variables.)
+sitem(tt(zstyles))(Output tt(zstyle) commands.)
+endsitem()
+
+If the var(state) is omitted, tt(all) is assumed.
+)
+
+With the exception of `tt(all)', every var(state) can be abbreviated by
+any prefix, even a single letter; thus tt(a) is the same as tt(aliases),
+tt(z) is the same as tt(zstyles), etc.
+enditem()
+
+texinode(Prompt Themes)(ZLE Functions)(Utilities)(User Contributions)
+sect(Prompt Themes)
+
+subsect(Installation)
+
+You should make sure all the functions from the tt(Functions/Prompts)
+directory of the source distribution are available; they all begin with
+the string `tt(prompt_)' except for the special function`tt(promptinit)'.
+You also need the `tt(colors)' function from tt(Functions/Misc).  All of
+these functions may already have been installed on your system; if not,
+you will need to find them and copy them.  The directory should appear as
+one of the elements of the tt(fpath) array (this should already be the
+case if they were installed), and at least the function tt(promptinit)
+should be autoloaded; it will autoload the rest.  Finally, to initialize
+the use of the system you need to call the tt(promptinit) function.  The
+following code in your tt(.zshrc) will arrange for this; assume the
+functions are stored in the directory tt(~/myfns):
+
+example(fpath=(~/myfns $fpath)
+autoload -U promptinit
+promptinit)
+
+subsect(Theme Selection)
+
+Use the tt(prompt) command to select your preferred theme.  This command
+may be added to your tt(.zshrc) following the call to tt(promptinit) in
+order to start zsh with a theme already selected.
+
+startitem()
+xitem(tt(prompt) [ tt(-c) | tt(-l) ])
+xitem(tt(prompt) [ tt(-p) | tt(-h) ] [ var(theme) ... ])
+item(tt(prompt) [ tt(-s) ] var(theme) [ var(arg) ... ])(
+Set or examine the prompt theme.  With no options and a var(theme)
+argument, the theme with that name is set as the current theme.  The
+available themes are determined at run time; use the tt(-l) option to see
+a list.  The special var(theme) `tt(random)' selects at random one of the
+available themes and sets your prompt to that.
+
+In some cases the var(theme) may be modified by one or more arguments,
+which should be given after the theme name.  See the help for each theme
+for descriptions of these arguments.
+
+Options are:
+
+startsitem()
+sitem(tt(-c))(Show the currently selected theme and its parameters, if any.)
+sitem(tt(-l))(List all available prompt themes.)
+sitem(tt(-p))(Preview the theme named by var(theme), or all themes if no
+var(theme) is given.)
+sitem(tt(-h))(Show help for the theme named by var(theme), or for the
+tt(prompt) function if no var(theme) is given.)
+sitem(tt(-s))(Set var(theme) as the current theme and save state.)
+endsitem()
+)
+item(tt(prompt_)var(theme)tt(_setup))(
+Each available var(theme) has a setup function which is called by the
+tt(prompt) function to install that theme.  This function may define
+other functions as necessary to maintain the prompt, including functions
+used to preview the prompt or provide help for its use.  You should not
+normally call a theme's setup function directly.
+)
+enditem()
+
+texinode(ZLE Functions)(Other Functions)(Prompt Themes)(User Contributions)
+sect(ZLE Functions)
+
+subsect(Widgets)
+
+These functions all implement user-defined ZLE widgets (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) which can be bound to keystrokes in interactive shells.  To use them,
+your tt(.zshrc) should contain lines of the form
+
+example(autoload var(function)
+zle -N var(function))
+
+followed by an appropriate tt(bindkey) command to associate the function
+with a key sequence.  Suggested bindings are described below.
+
+startitem()
+tindex(bash-forward-word)
+tindex(bash-backward-word)
+tindex(bash-kill-word)
+tindex(bash-backward-kill-word)
+tindex(bash-transpose-words)
+tindex(bash-up-case-word)
+tindex(bash-down-case-word)
+xitem(tt(bash-forward-word), tt(bash-backward-word))
+xitem(tt(bash-kill-word), tt(bash-backward-kill-word))
+xitem(tt(bash-up-case-word), tt(bash-down-case-word))
+item(tt(bash-transpose-words))(
+These work similarly to the corresponding builtin zle functions without the
+`tt(bash-)' prefix, but a word is considered to consist of alphanumeric
+characters only.  If you wish to replace your existing bindings with these
+four widgets, the following is sufficient:
+
+example(for widget in kill-word backward-kill-word \ 
+forward-word backward-word \ 
+up-case-word down-case-word \ 
+transpose-words; do 
+  autoload bash-$widget 
+  zle -N $widget bash-$widget
+done)
+)
+tindex(cycle-completion-positions)
+item(tt(cycle-completion-positions))(
+After inserting an unambiguous string into the command line, the new
+function based completion system may know about multiple places in
+this string where characters are missing or differ from at least one
+of the possible matches.  It will then place the cursor on the
+position it considers to be the most interesting one, i.e. the one
+where one can disambiguate between as many matches as possible with as 
+little typing as possible.
+
+This widget allows the cursor to be easily moved to the other interesting
+spots.  It can be invoked repeatedly to cycle between all positions
+reported by the completion system.
+)
+tindex(edit-command-line)
+item(tt(edit-command-line))(
+Edit the command line using your visual editor, as in tt(ksh).
+
+example(bindkey -M vicmd v edit-command-line)
+)
+tindex(history-beginning-search-backward-end)
+tindex(history-beginning-search-forward-end)
+item(tt(history-search-end))(
+This function implements the widgets
+tt(history-beginning-search-backward-end) and
+tt(history-beginning-search-forward-end).  These commands work by first
+calling the corresponding builtin widget (see
+ifzman(`History Control' in zmanref(zshzle))\
+ifnzman(noderef(History Control))\
+) and then moving the cursor to the end of the line.  The original cursor
+position is remembered and restored before calling the builtin widget a
+second time, so that the same search is repeated to look farther through
+the history.
+
+Although you tt(autoload) only one function, the commands to use it are
+slightly different because it implements two widgets.
+
+example(zle -N history-beginning-search-backward-end \ 
+       history-search-end
+zle -N history-beginning-search-forward-end \ 
+       history-search-end
+bindkey '\e^P' history-beginning-search-backward-end
+bindkey '\e^N' history-beginning-search-forward-end)
+)
+tindex(incarg)
+vindex(incarg, use of)
+item(tt(incarg))(
+Typing the keystrokes for this widget with the cursor placed on or to the
+left of an integer causes that integer to be incremented by one.  With a
+numeric prefix argument, the number is incremented by the amount of the
+argument (decremented if the prefix argument is negative).  The shell
+parameter tt(incarg) may be set to change the default increment something
+other than one.
+
+example(bindkey '^X+' incarg)
+)
+tindex(incremental-complete-word)
+item(tt(incremental-complete-word))(
+This allows incremental completion of a word.  After starting this
+command, a list of completion choices can be shown after every character
+you type, which you can delete with tt(^H) or tt(DEL).  Pressing return
+accepts the completion so far and returns you to normal editing (that is,
+the command line is em(not) immediately executed).  You can hit tt(TAB) to
+do normal completion, tt(^G) to abort back to the state when you started,
+and tt(^D) to list the matches.
+
+This works only with the new function based completion system.
+
+example(bindkey '^Xi' incremental-complete-word)
+)
+tindex(insert-files)
+item(tt(insert-files))(
+This function allows you type a file pattern, and see the results of the
+expansion at each step.  When you hit return, all expansions are inserted
+into the command line.
+
+example(bindkey '^Xf' insert-files)
+)
+tindex(predict-on)
+tindex(predict-off)
+item(tt(predict-on))(
+This set of functions implements predictive typing using history search.
+After tt(predict-on), typing characters causes the editor to look backward
+in the history for the first line beginning with what you have typed so
+far.  After tt(predict-off), editing returns to normal for the line found.
+In fact, you often don't even need to use tt(predict-off), because if the
+line doesn't match something in the history, adding a key performs
+standard completion, and then inserts itself if no completions were found.
+However, editing in the middle of a line is liable to confuse prediction;
+see the tt(toggle) style below.
+
+With the function based completion system (which is needed for this), you
+should be able to type tt(TAB) at almost any point to advance the cursor
+to the next ``interesting'' character position (usually the end of the
+current word, but sometimes somewhere in the middle of the word).  And of
+course as soon as the entire line is what you want, you can accept with
+return, without needing to move the cursor to the end first.
+
+The first time tt(predict-on) is used, it creates several additional
+widget functions:
+
+startsitem()
+sitem(tt(delete-backward-and-predict))(Replaces the tt(backward-delete-char)
+widget.  You do not need to bind this yourself.)
+sitem(tt(insert-and-predict))(Implements predictive typing by replacing the
+tt(self-insert) widget.  You do not need to bind this yourself.)
+sitem(tt(predict-off))(Turns off predictive typing.)
+endsitem()
+
+Although you tt(autoload) only the tt(predict-on) function, it is
+necessary to create a keybinding for tt(predict-off) as well.
+
+example(zle -N predict-on
+zle -N predict-off
+bindkey '^X^Z' predict-on
+bindkey '^Z' predict-off)
+)
+findex(smart-insert-last-word)
+item(tt(smart-insert-last-word))(
+This function may replace the tt(insert-last-word) widget, like so:
+
+example(zle -N insert-last-word smart-insert-last-word)
+
+With a numeric prefix, it behaves like tt(insert-last-word), except that
+words in comments are ignored when tt(INTERACTIVE_COMMENTS) is set.
+
+Otherwise, the rightmost ``interesting'' word from the previous command is
+found and inserted.  The default definition of ``interesting'' is that the
+word contains at least one alphabetic character, slash, or backslash.
+This definition may be overridden by use of the tt(match) style.  The
+context used to look up the style is the widget name, so usually the
+context is tt(:insert-last-word).  However, you can bind this function to
+different widgets to use different patterns:
+
+example(zle -N insert-last-assignment smart-insert-last-word
+zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
+bindkey '\e=' insert-last-assignment)
+)
+enditem()
+
+subsect(Styles)
+
+The behavior of several of the above widgets can be controlled by the use
+of the tt(zstyle) mechanism.  In particular, widgets that interact with
+the completion system pass along their context to any completions that
+they invoke.
+
+startitem()
+kindex(break-keys, widget style)
+item(tt(break-keys))(
+This style is used by the tt(incremental-complete-word) widget. Its value
+should be a pattern, and all keys matching this pattern will cause the
+widget to stop incremental completion without the key having any further
+effect. Like all styles used directly by
+tt(incremental-complete-word), this style is looked up using the
+context `tt(:incremental)'.
+)
+kindex(completer, completion style)
+item(tt(completer))(
+The tt(incremental-complete-word) and tt(insert-and-predict) widgets set
+up their top-level context name before calling completion.  This allows
+one to define different sets of completer functions for normal completion
+and for these widgets.  For example, to use completion, approximation and
+correction for normal completion, completion and correction for
+incremental completion and only completion for prediction one could use:
+
+example(zstyle ':completion:*' completer \ 
+        _complete _correct _approximate
+zstyle ':completion:incremental:*' completer \ 
+        _complete _correct
+zstyle ':completion:predict:*' completer \ 
+        _complete)
+
+It is a good idea to restrict the completers used in prediction, because
+they may be automatically invoked as you type.  The tt(_list) and
+tt(_menu) completers should never be used with prediction.  The
+tt(_approximate), tt(_correct), tt(_expand), and tt(_match) completers may
+be used, but be aware that they may change characters anywhere in the word
+behind the cursor, so you need to watch carefully that the result is what
+you intended.
+)
+kindex(cursor, completion style)
+item(tt(cursor))(
+The tt(insert-and-predict) widget uses this style, in the context
+`tt(:predict)', to decide where to place the cursor after completion has
+been tried.  Values are:
+
+startitem()
+item(tt(complete))(
+The cursor is left where it was when completion finished, but only if
+it is after a character equal to the one just inserted by the user.  If 
+it is after another character, this value is the same as `tt(key)'.
+)
+item(tt(key))(
+The cursor is left
+after the var(n)th occurrence of the character just inserted, where
+var(n) is the number of times that character appeared in the word
+before completion was attempted.  In short, this has the effect of
+leaving the cursor after the character just typed even if the
+completion code found out that no other characters need to be inserted 
+at that position.
+)
+enditem()
+
+Any other value for this style unconditionally leaves the cursor at the
+position where the completion code left it.
+)
+kindex(list, widget style)
+item(tt(list))(
+When using the tt(incremental-complete-word) widget, this style says
+if the matches should be listed on every key press (if they fit on the 
+screen).  Use the context prefix `tt(:completion:incremental)'.
+
+The tt(insert-and-predict) widget uses this style to decide if the
+completion should be shown even if there is only one possible completion.
+This is done if the value of this style is the string tt(always).  In this
+case the context is `tt(:predict)' (em(not) `tt(:completion:predict)').
+)
+kindex(match, widget style)
+item(tt(match))(
+This style is used by tt(smart-insert-last-word) to provide a pattern
+(using full tt(EXTENDED_GLOB) syntax) that matches an interesting word.
+The context is the name of the widget to which tt(smart-insert-last-word)
+is bound (see above).  The default behavior of tt(smart-insert-last-word)
+is equivalent to:
+
+example(zstyle :insert-last-word match '*[[:alpha:]/\\]*')
+
+However, you might want to include words that contain spaces:
+
+example(zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*')
+
+Or include numbers as long as the word is at least two characters long:
+
+example(zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*')
+
+The above example causes redirections like "2>" to be included.
+)
+kindex(prompt, widget style)
+item(tt(prompt))(
+The tt(incremental-complete-word) widget shows the value of this
+style in the status line during incremental completion.  The string
+value may contain any of the following substrings in the manner of
+the tt(PS1) and other prompt parameters:
+
+startitem()
+item(tt(%c))(
+Replaced by the name of the completer function that generated the
+matches (without the leading underscore).
+)
+item(tt(%l))(
+When the tt(list) style is set,
+replaced by `tt(...)' if the list of matches is too long to fit on the
+screen and with an empty string otherwise.  If the tt(list) style is
+`false' or not set, `tt(%l)' is always removed.
+)
+item(tt(%n))(
+Replaced by the number of matches generated.
+)
+item(tt(%s))(
+Replaced by `tt(-no match-)', `tt(-no prefix-)', or an empty string
+if there is no completion matching the word on the line, if the
+matches have no common prefix different from the word on the line, or
+if there is such a common prefix, respectively.
+)
+item(tt(%u))(
+Replaced by the unambiguous part of all matches, if there
+is any, and if it is different from the word on the line.
+)
+enditem()
+
+Like `tt(break-keys)', this uses the `tt(:incremental)' context.
+)
+kindex(stop-keys, widget style)
+item(tt(stop-keys))(
+This style is used by the tt(incremental-complete-word) widget.  Its value
+is treated similarly to the one for the tt(break-keys) style (and uses 
+the same context: `tt(:incremental)').  However, in
+this case all keys matching the pattern given as its value will stop
+incremental completion and will then execute their usual function.
+)
+kindex(toggle, widget style)
+item(tt(toggle))(
+This boolean style is used by tt(predict-on) and its related widgets in
+the context `tt(:predict)'.  If set to one of the standard `true' values,
+predictive typing is automatically toggled off in situations where it is
+unlikely to be useful, such as when editing a multi-line buffer or after
+moving into the middle of a line and then deleting a character.  The
+default is to leave prediction turned on until an explicit call to
+tt(predict-off).
+)
+kindex(verbose, widget style)
+item(tt(verbose))(
+This boolean style is used by tt(predict-on) and its related widgets in
+the context `tt(:predict)'.  If set to one of the standard `true' values,
+these widgets display a message below the prompt when the predictive state
+is toggled.  This is most useful in combination with the tt(toggle) style.
+The default does not display these messages.
+)
+enditem()
+
+texinode(Other Functions)()(ZLE Functions)(User Contributions)
+sect(Other Functions)
+
+There are a large number of helpful functions in the tt(Functions/Misc)
+directory of the zsh distribution.  Most are very simple and do not
+require documentation here, but a few are worthy of special mention.
+
+subsect(Descriptions)
+
+startitem()
+findex(colors)
+item(tt(colors))(
+This function initializes several associative arrays to map color names to
+(and from) the ANSI standard eight-color terminal codes.  These are used
+by the prompt theme system (ifzman(see above)\
+ifnzman(noderef(Prompt Themes))).  You seldom should need to run
+tt(colors) more than once.
+
+The eight base colors are: black, red, green, yellow, blue, magenta, cyan,
+and white.  Each of these has codes for foreground and background.  In
+addition there are eight intensity attributes: bold, faint, standout,
+underline, blink, reverse, and conceal.  Finally, there are six codes used
+to negate attributes: none (reset all attributes to the defaults), normal
+(neither bold nor faint), no-standout, no-underline, no-blink, and
+no-reverse.
+
+Some terminals do not support all combinations of colors and intensities.
+
+The associative arrays are:
+
+startitem()
+xitem(color)
+item(colour)(
+Map all the color names to their integer codes, and integer codes to the
+color names.  The eight base names map to the foreground color codes, as
+do names prefixed with `tt(fg-)', such as `tt(fg-red)'.  Names prefixed
+with `tt(bg-)', such as `tt(bg-blue)', refer to the background codes.  The
+reverse mapping from code to color yields base name for foreground codes
+and the tt(bg-) form for backgrounds.
+
+Although it is a misnomer to call them `colors', these arrays also map the
+other fourteen attributes from names to codes and codes to names.
+)
+xitem(fg)
+xitem(fg_bold)
+item(fg_no_bold)(
+Map the eight basic color names to ANSI terminal escape sequences that set
+the corresponding foreground text properties.  The tt(fg) sequences change
+the color without changing the eight intensity attributes.
+)
+xitem(bg)
+xitem(bg_bold)
+item(bg_no_bold)(
+Map the eight basic color names to ANSI terminal escape sequences that set
+the corresponding background properties.  The tt(bg) sequences change the
+color without changing the eight intensity attributes.
+)
+enditem()
+
+In addition, the scalar parameters tt(reset_color) and tt(bold_color) are
+set to the ANSI terminal escapes that turn off all attributes and turn on
+bold intensity, respectively.
+)
+findex(fned)
+item(tt(fned) var(name))(
+Same as tt(zed -f).  This function does not appear in the zsh
+distribution, but can be created by linking tt(zed) to the name tt(fned)
+in some directory in your tt(fpath).
+)
+findex(is-at-least)
+item(tt(is-at-least) var(needed) [ var(present) ])(
+Perform a greater-than-or-equal-to comparison of two strings having the
+format of a zsh version number; that is, a string of numbers and text with
+segments separated by dots or dashes.  If the var(present) string is not
+provided, tt($ZSH_VERSION) is used.  Segments are paired left-to-right in
+the two strings with leading non-number parts ignored.  If one string has
+fewer segments than the other, the missing segments are considered zero.
+
+This is useful in startup files to set options and other state that are
+not available in all versions of zsh.
+
+example(is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
+is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
+is-at-least 2.6-17 || print "You can't use is-at-least here.")
+)
+findex(nslookup)
+item(tt(nslookup) [ var(arg) ... ])(
+This wrapper function for the tt(nslookup) command requires the
+tt(zsh/zpty) module (see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zpty Module))\
+).  It behaves exactly like the standard tt(nslookup)
+except that it provides customizable prompts (including a right-side
+prompt) and completion of nslookup commands, host names, etc. (if you use
+the function-based completion system).  Completion styles may be set with
+the context prefix `tt(:completion:nslookup)'.
+
+See also the tt(pager), tt(prompt) and tt(rprompt) styles below.
+)
+item(tt(run-help))(
+See `Accessing On-Line Help'
+ifzman(above)\
+ifnzman((noderef(Utilities))).
+)
+findex(zed)
+item(tt(zed) [ tt(-f) ] var(name))(
+This function uses the ZLE editor to edit a file or function.  It rebinds
+the return key to insert a line break, and adds bindings for `tt(^X^W)' in
+the tt(emacs) keymap and `tt(ZZ)' in the tt(vicmd) keymap to accept (and
+therefore write, in the case of a file) the edited file or function.
+Keybindings are otherwise the standard ones; completion is available, and
+styles may be set with the context prefix `tt(:completion:zed)'.
+
+Only one var(name) argument is recognized (additional arguments are
+ignored).  If the tt(-f) option is given, the name is taken to be that of
+a function; if the function is marked for autoloading, tt(zed) searches
+for it in the tt(fpath) and loads it.  Note that functions edited this way
+are installed into the current shell, but em(not) written back to the
+autoload file.
+
+Without tt(-f), var(name) is the path name of the file to edit, which need
+not exist; it is created on write, if necessary.
+)
+findex(zcp)
+findex(zln)
+xitem(tt(zcp) [ tt(-finqQvw) ] var(srcpat) var(dest))
+item(tt(zln) [ tt(-finqQsvw) ] var(srcpat) var(dest))(
+Same as tt(zmv -C) and tt(zmv -L), respectively.  These functions do not
+appear in the zsh distribution, but can be created by linking tt(zmv) to
+the names tt(zcp) and tt(zln) in some directory in your tt(fpath).
+)
+item(tt(zkbd))(
+See `Keyboard Definition'
+ifzman(above)\
+ifnzman((noderef(Utilities))).
+)
+findex(zmv)
+item(tt(zmv) [ tt(-finqQsvw) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )(
+Move (usually, rename) files matching the pattern var(srcpat) to
+corresponding files having names of the form given by var(dest), where
+var(srcpat) contains parentheses surrounding patterns which will be
+replaced in turn by $1, $2, ... in var(dest).  For example,
+
+example(zmv '(*).lis' '$1.txt')
+
+renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to
+`tt(my.old.stuff.txt)', and so on.
+
+The pattern is always treated as an tt(EXTENDED_GLOB) pattern.  Any file
+whose name is not changed by the substitution is simply ignored.  Any
+error (a substitution resulted in an empty string, two substitutions gave
+the same result, the destination was an existing regular file and tt(-f)
+was not given) causes the entire function to abort without doing anything.
+
+Options:
+
+startsitem()
+sitem(tt(-f))(Force overwriting of destination files.  Not currently
+passed down to the tt(mv)/tt(cp)/tt(ln) command due to vagaries of
+implementations (but you can use tt(-o-f) to do that).)
+sitem(tt(-i))(Interactive: show each line to be executed and ask the user
+whether to execute it.  `Y' or `y' will execute it, anything else will
+skip it.  Note that you just need to type one character.)
+sitem(tt(-n))(No execution: print what would happen, but don't do it.)
+sitem(tt(-q))(Turn bare glob qualifiers off: now assumed by default, so
+this has no effect.)
+sitem(tt(-Q))(Force bare glob qualifiers on.  Don't turn this on unless
+you are actually using glob qualifiers in a pattern.)
+sitem(tt(-s))(Symbolic, passed down to tt(ln); only works with tt(-L).)
+sitem(tt(-v))(Verbose: print each command as it's being executed.)
+sitem(tt(-w))(Pick out wildcard parts of the pattern, as described above,
+and implicitly add parentheses for referring to them.)
+sxitem(tt(-C))
+sxitem(tt(-L))
+sitem(tt(-M))(Force tt(cp), tt(ln) or tt(mv), respectively, regardless of
+the name of the function.)
+sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) or
+tt(mv).  Whatever it does, it should at least understand the form
+ifzman(`var(program) tt(-)tt(-) var(oldname) var(newname)')\
+ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname)))
+where var(oldname) and var(newname) are filenames generated by tt(zmv).)
+sitem(tt(-o) var(optstring))(The var(optstring) is split into words and
+passed down verbatim to the tt(cp), tt(ln) or tt(mv) command called to
+perform the work.  It should probably begin with a `tt(-)'.)
+endsitem()
+
+For more complete examples and other implementation details, see the
+tt(zmv) source file, usually located in one of the directories named in
+your tt(fpath), or in tt(Functions/Misc/zmv) in the zsh distribution.
+)
+item(tt(zrecompile))(
+See `Recompiling Functions'
+ifzman(above)\
+ifnzman((noderef(Utilities))).
+)
+findex(zstyle+)
+item(tt(zstyle+) var(context) var(style) var(value) [ + var(subcontext) var(style) var(value) ... ])(
+This makes defining styles a bit simpler by using a single `tt(+)' as a
+special token that allows you to append a context name to the previously
+used context name.  Like this:
+
+example(zstyle+ ':foo:bar' style1 value1 \ 
+      + ':baz'     style2 value2 \ 
+      + ':frob'    style3 value3)
+
+This defines `style1' with `value1' for the context tt(:foo:bar) as usual,
+but it also defines `style2' with `value2' for the context
+tt(:foo:bar:baz) and `style3' with `value3' for tt(:foo:bar:frob).  Any
+var(subcontext) may be the empty string to re-use the first context
+unchanged.
+)
+enditem()
+
+subsect(Styles)
+
+startitem()
+kindex(insert-tab, completion style)
+item(tt(insert-tab))(
+The tt(zed) function em(sets) this style in context `tt(:completion:zed:*)'
+to turn off completion when tt(TAB) is typed at the beginning of a line.
+You may override this by setting your own value for this context and style.
+)
+kindex(pager, nslookup style)
+item(tt(pager))(
+The tt(nslookup) function looks up this style in the context
+`tt(:nslookup)' to determine the program used to display output that does
+not fit on a single screen.
+)
+kindex(prompt, nslookup style)
+kindex(rprompt, nslookup style)
+xitem(tt(prompt))
+item(tt(rprompt))(
+The tt(nslookup) function looks up this style in the context
+`tt(:nslookup)' to set the prompt and the right-side prompt, respectively.
+The usual expansions for the tt(PS1) and tt(RPS1) parameters may be used
+(see
+ifzman(zmanref(zshmisc))\
+ifnzman(noderef(Prompt Expansion))\
+).
+)
+enditem()
-- 
cgit 1.4.1