diff options
Diffstat (limited to 'Doc/Zsh/contrib.yo')
| -rw-r--r-- | Doc/Zsh/contrib.yo | 158 |
1 files changed, 113 insertions, 45 deletions
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index bb6613ece..1c1a66a3b 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -45,9 +45,8 @@ 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. +Help files are installed by default to a subdirectory of tt(/usr/share/zsh) +or tt(/usr/local/share/zsh). To create your own help files with tt(helpfiles), choose or create a directory where the individual command help files will reside. For @@ -55,22 +54,22 @@ 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) +perl ~/zsh-version()/Util/helpfiles ~/zsh_help) + +vindex(HELPDIR) +The tt(HELPDIR) parameter tells tt(run-help) where to look for the help +files. When unset, it uses the default installation path. +To use your own set of help files, set this to the appropriate path +in one of your startup files: + +example(HELPDIR=~/zsh_help) findex(run-help, use of) -Next, to use the tt(run-help) function, you need to add lines something +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. +autoload run-help) 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 @@ -827,17 +826,32 @@ item(tt(check-for-changes))( If enabled, this style causes the tt(%c) and tt(%u) format escapes to show when the working directory has uncommitted changes. The strings displayed by these escapes can be controlled via the tt(stagedstr) and tt(unstagedstr) -styles. The only backends that currently support this option are tt(git) and -tt(hg) (tt(hg) only supports unstaged). +styles. The only backends that currently support this option are tt(git), +tt(hg), and tt(bzr) (the latter two only support unstaged). For this style to be evaluated with the tt(hg) backend, the tt(get-revision) style needs to be set and the tt(use-simple) style needs to be unset. The latter is the default; the former is not. +With the tt(bzr) backend, em(lightweight checkouts) only honor this style if +the tt(use-server) style is set. + Note, the actions taken if this style is enabled are potentially expensive (read: they may be slow, depending on how big the current repository is). Therefore, it is disabled by default. ) +kindex(check-for-staged-changes) +item(tt(check-for-staged-changes))( +This style is like tt(check-for-changes), but it never checks the worktree +files, only the metadata in the tt(.${vcs}) dir. Therefore, +this style initializes only the tt(%c) escape (with tt(stagedstr)) but +not the tt(%u) escape. This style is faster than tt(check-for-changes). + +In the tt(git) backend, this style checks for changes in the index. +Other backends do not currently implement this style. + +This style is disabled by default. +) kindex(stagedstr) item(tt(stagedstr))( This string will be used in the tt(%c) escape if there are staged changes in @@ -863,7 +877,7 @@ when this style is looked up. For example, this style can be used to use binaries from non-default installation directories. Assume, tt(git) is installed in /usr/bin but -your sysadmin installed a newer version in /usr/bin/local. Instead of +your sysadmin installed a newer version in /usr/local/bin. Instead of changing the order of your tt($PATH) parameter, you can do this: example(zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git) ) @@ -881,6 +895,9 @@ backend is only usable if you have set the environment variable tt(P4CONFIG) to a file name and have corresponding files in the root directories of each Perforce client. See comments in the function tt(VCS_INFO_detect_p4) for more detail. + +The Bazaar backend (tt(bzr)) uses this to permit contacting the server +about lightweight checkouts, see the tt(check-for-changes) style. ) kindex(use-simple) item(tt(use-simple))( @@ -942,6 +959,7 @@ sitem(tt(enable))(ALL) sitem(tt(disable))((empty list)) sitem(tt(disable-patterns))((empty list)) sitem(tt(check-for-changes))(false) +sitem(tt(check-for-staged-changes))(false) sitem(tt(stagedstr))((string: "S")) sitem(tt(unstagedstr))((string: "U")) sitem(tt(command))((empty string)) @@ -1321,6 +1339,11 @@ This hooks is called when no version control system was detected. The `hook_com' parameter is not used. ) +item(tt(post-backend))( +Called as soon as the backend has finished collecting information. + +The `tt(hook_com)' keys available are as for the tt(set-message) hook. +) item(tt(post-quilt))( Called after the tt(quilt) support is done. The following information is passed as arguments to the hook: 1. the quilt-support mode (`addon' or @@ -1481,22 +1504,15 @@ function +vi-hgbookmarks+LPAR()RPAR() { # This makes the bookmarks string use only those # bookmarks. If there's more than one, it # concatenates them using commas. - local s i # The bookmarks returned by `hg' are available in - # the functions positional parameters. - (( $# == 0 )) && return 0 - for i in "$@"; do - if [[ $i == sh/* ]]; then - [[ -n $s ]] && s=$s, - s=${s}$i - fi - done + # the function's positional parameters. + local s="${(Mj:,:)@:#sh/*}" # Now, the communication with the code that calls # the hook functions is done via the hook_com[] - # hash. The key, at which the `gen-hg-bookmark-string' - # hook looks at is `hg-bookmark-string'. So: + # hash. The key at which the `gen-hg-bookmark-string' + # hook looks is `hg-bookmark-string'. So: hook_com[hg-bookmark-string]=$s - # And to signal, that we want to use the sting we + # And to signal that we want to use the string we # just generated, set the special variable `ret' to # something other than the default zero: ret=1 @@ -1874,6 +1890,12 @@ Edit the command line using your visual editor, as in tt(ksh). example(bindkey -M vicmd v edit-command-line) ) +tindex(expand-absolute-path) +item(tt(expand-absolute-path))( +Expand the file name under the cursor to an absolute path, resolving +symbolic links. Where possible, the initial path segment is turned +into a named directory or reference to a user's home directory. +) tindex(history-beginning-search-backward-end) tindex(history-beginning-search-forward-end) item(tt(history-search-end))( @@ -2306,6 +2328,32 @@ The name is a slight misnomer, as in fact the shell's own minibuffer is not used. Hence it is still possible to call tt(executed-named-cmd) and similar functions while reading a value. ) +tindex(replace-argument) +tindex(replace-argument-edit) +item(tt(replace-argument), tt(replace-argument-edit)) +( +The function tt(replace-argument) can be used to replace a command +line argument in the current command line or, if the current command +line is empty, in the last command line executed (the new command line +is not executed). Arguments are as delimited by standard shell syntax, + +If a numeric argument is given, that specifies the argument to be +replaced. 0 means the command name, as in history expansion. +A negative numeric argument counts backward from the last word. + +If no numeric argument is given, the current argument is replaced; +this is the last argument if the previous history line is being used. + +The function prompts for a replacement argument. + +If the widget contains the string tt(edit), for example is defined as + +example(zle -N replace-argument-edit replace-argument) + +then the function presents the current value of the argument for +editing, otherwise the editing buffer for the replacement is +initially empty. +) tindex(replace-string) tindex(replace-string-again) tindex(replace-pattern) @@ -2444,6 +2492,25 @@ The style tt(whence) is available in the context tt(:zle:$WIDGET); this may be set to an array to give the command and options that will be used to investigate the command word found. The default is tt(whence -c). ) +tindex(zcalc-auto-insert) +item(tt(zcalc-auto-insert))( +This function is useful together with the tt(zcalc) function described in +ifzman(the section Mathematical Functions)\ +ifnzman(noderef(Mathematical Functions)). +It should be bound to a key representing a binary operator such +as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'. When running in zcalc, +if the key occurs at the start of the line or immediately following +an open parenthesis, the text tt("ans ") is inserted before the +representation of the key itself. This allows easy use of the +answer from the previous calculation in the current line. The +text to be inserted before the symbol typed can be modified by setting +the variable tt(ZCALC_AUTO_INSERT_PREFIX). + +Hence, for example, typing `tt(PLUS()12)' followed by return adds 12 +to the previous result. + +When not in zcalc, the key simply inserts the symbol itself. +) enditem() subsect(Utility Functions) @@ -2899,7 +2966,7 @@ file name is matched against the pattern, regardless of how the file was passed to the handler. The file is resolved to a full path using the tt(:A) modifier described in ifzman(the subsection Modifers in zmanref(zshexpn))\ -ifnzman(noderef(Modifiers))); +ifnzman(noderef(Modifiers)); this means that symbolic links are resolved where possible, so that links into other file systems behave in the correct fashion. ) @@ -3370,21 +3437,22 @@ 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. +The eight base colors are: tt(black), tt(red), tt(green), tt(yellow), +tt(blue), tt(magenta), tt(cyan), and tt(white). Each of these has codes for +foreground and background. In addition there are seven intensity attributes: +tt(bold), tt(faint), tt(standout), tt(underline), tt(blink), tt(reverse), +and tt(conceal). Finally, there are seven codes used to negate attributes: +tt(none) (reset all attributes to the defaults), tt(normal) +(neither bold nor faint), tt(no-standout), tt(no-underline), tt(no-blink), +tt(no-reverse), and tt(no-conceal). Some terminals do not support all combinations of colors and intensities. The associative arrays are: startitem() -xitem(color) -item(colour)( +xitem(tt(color)) +item(tt(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 @@ -3395,16 +3463,16 @@ 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)( +xitem(tt(fg)) +xitem(tt(fg_bold)) +item(tt(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)( +xitem(tt(bg)) +xitem(tt(bg_bold)) +item(tt(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. |