From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8518 invoked from network); 4 Sep 2000 20:57:20 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 4 Sep 2000 20:57:20 -0000 Received: (qmail 14182 invoked by alias); 4 Sep 2000 20:56:57 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 12742 Received: (qmail 14172 invoked from network); 4 Sep 2000 20:56:47 -0000 From: "Bart Schaefer" Message-Id: <1000904205637.ZM17241@candle.brasslantern.com> Date: Mon, 4 Sep 2000 20:56:36 +0000 X-Mailer: Z-Mail (5.0.0 30July97) To: zsh-workers@sunsite.auc.dk Subject: PATCH: "User Contributions" manual, & misc. MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable As threatened in 12467, this adds an entirely new chapter of the manual and uses it to document a variety of things that deserve mention but that= don't really fit anywhere else. I've also moved incremental-complete-wor= d and predict-on documentation to this chapter, and taken the opportunity t= o change the zstyle context used by predict-on for most of its styles. Sven, if you'd care to make similar changes to incremental-complete-word and update the corresponding sections of this doc, I'm sure your actions would be met with the usual unanimous approbation. Other misc. stuff in this patch includes fixing a cross-reference in the builtins manual, correcting a few typos, changing `prompt -s theme' to require an argument and set that theme even though saving it is not yet implemented, and changing history-search-end to use the mark rather than a global parameter to keep track of the old cursor position. There's probably some stuff that I missed -- in particular, I just notice= d that I didn't mention Misc/make-zsh-urls anywhere, and I probably could have thrown in a few more index entries -- so feel free to jump in with more stuff or to correct anything I may have gotten wrong. Index: Doc/.distfiles =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -4,11 +4,11 @@ version.yo zmacros.yo zman.yo ztexi.yo zsh.yo zshbuiltins.yo zshcompctl.yo zshcompsys.yo zshcompwid.yo zshexpn.yo zshmisc.yo zshmodules.yo zshoptions.yo zshparam.yo - zshzftpsys.yo zshzle.yo + zshzftpsys.yo zshzle.yo zshcontrib.yo zsh.texi zsh.1 zshbuiltins.1 zshcompctl.1 zshcompsys.1 zshcompwid.1 zshexpn.1= zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshzle.1 zshall.1 - zshzftpsys.1 + zshzftpsys.1 zshcontrib.1 ' = DISTFILES_DOC=3D' Index: Doc/Makefile.in =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -46,7 +46,7 @@ = # man pages to install MAN =3D zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 zshcompsys.1 \ -zshexpn.1 zshmisc.1 zshmodules.1 \ +zshcontrib.1 zshexpn.1 zshmisc.1 zshmodules.1 \ zshoptions.1 zshparam.1 zshzftpsys.1 zshzle.1 zshall.1 = # yodl documentation @@ -64,7 +64,7 @@ = YODLSRC =3D zmacros.yo zman.yo ztexi.yo Zsh/arith.yo Zsh/builtins.yo \ Zsh/compat.yo Zsh/compctl.yo Zsh/compsys.yo Zsh/compwid.yo Zsh/cond.yo \= -Zsh/exec.yo Zsh/expn.yo \ +Zsh/contrib.yo Zsh/exec.yo Zsh/expn.yo \ Zsh/filelist.yo Zsh/files.yo Zsh/func.yo Zsh/grammar.yo Zsh/manual.yo \ Zsh/index.yo Zsh/intro.yo Zsh/invoke.yo Zsh/jobs.yo Zsh/metafaq.yo \ Zsh/modules.yo Zsh/modlist.yo Zsh/modmenu.yo Zsh/manmodmenu.yo $(MODDOCS= RC) \ @@ -166,6 +166,8 @@ zshcompwid.1: Zsh/compwid.yo = zshcompsys.1: Zsh/compsys.yo + +zshcontrib.1: Zsh/contrib.yo = zshexpn.1: Zsh/expn.yo = Index: Doc/zsh.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -64,6 +64,7 @@ ifnzman(includefile(Zsh/compctl.yo))=01 ifnzman(includefile(Zsh/modules.yo))=01 ifnzman(includefile(Zsh/zftpsys.yo))=01 +ifnzman(includefile(Zsh/contrib.yo))=01 ifzshall(\ def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\ CMT() @@ -78,6 +79,7 @@ source(zshcompctl) source(zshmodules) source(zshzftpsys) +source(zshcontrib) manpage(ZSHALL)(1)(date())(zsh version()) )\ ifzman(includefile(Zsh/filelist.yo))=01 Index: Doc/Zsh/.distfiles =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -10,5 +10,5 @@ mod_zprof.yo mod_zpty.yo modules.yo modlist.yo modmenu.yo manmodmenu.yo options.yo params.yo prompt.yo redirect.yo restricted.yo seealso.yo - zftpsys.yo zle.yo + zftpsys.yo zle.yo contrib.yo ' Index: Doc/Zsh/builtins.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -702,7 +702,10 @@ expressions, as appropriate. ) item(tt(-P))( -Perform prompt expansion (see noderef(Prompt Expansion)). +Perform prompt expansion (see +ifzman(zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion))\ +). ) enditem() ) Index: Doc/Zsh/compsys.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -901,14 +901,6 @@ it may be useful to set this style to something like `tt(specify: %d)'. = Note that this may not work for some commands. ) -kindex(break-keys, completion style) -item(tt(break-keys))( -This style is used by the tt(incremental-complete-word) widget (found -in the tt(Functions/Zle) directory of the distribution). 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. -) kindex(cache-path, completion style) item(tt(cache-path))( This style defines the path where any cache files containing dumped @@ -969,19 +961,6 @@ exceptions to this rule are the tt(_ignored) and tt(_prefix) completers. = -Note that the widget functions from the distribution that call the -completion code (namely, the tt(incremental-complete-word) and the -tt(predict-on) 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) - The default value for this style is tt(_complete _ignored), i.e. normally only completion will be done, first using the tt(ignored-patterns) style and the tt($fignore) array and then without = @@ -1000,31 +979,6 @@ insertion of matches should be delayed unconditionally. The default is = `true'. ) -kindex(cursor, completion style) -item(tt(cursor))( -The tt(predict-on) widget uses this style 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(disable-stat, completion style) item(tt(disable-stat))( This is used with an empty tag by the function completing for the @@ -1426,21 +1380,9 @@ ) kindex(list, completion style) item(tt(list))( -This style is used by the tt(_history_complete_word) bindable command -(using the context prefix `tt(:completion:history-words)') and by the -tt(incremental-complete-word) widget (using the context prefix -`tt(:completion:incremental)). - -The tt(_history_complete_word) bindable command uses this style to -decide if the available matches should be shown. - -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). - -The tt(predict-on) 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). +This style is used by the tt(_history_complete_word) bindable command to= +decide if the available matches should be shown. Use the context prefix= +`tt(:completion:history-words)'. ) kindex(list-colors, completion style) item(tt(list-colors))( @@ -1780,39 +1722,6 @@ = The default style for this style is `true'. ) -kindex(prompt, completion 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() -) kindex(range, completion style) item(tt(range))( This is used by the tt(_history) completer and the @@ -1896,14 +1805,6 @@ and will stop when the last match is inserted. If this style is set to `tt(verbose)' a message will be displayed when the last match is reached. -) -kindex(stop-keys, completion 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. 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(subst-globs-only, completion style) item(tt(subst-globs-only))( Index: Doc/Zsh/manual.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -31,6 +31,7 @@ menu(Completion Using compctl) menu(Zsh Modules) menu(Zftp Function System) +menu(User Contributions) = --- Indices --- = @@ -138,6 +139,14 @@ menu(Installation) menu(Zftp Functions) menu(Miscellaneous Features) + +User Contributions + +menu(Utilities) +menu(Prompt Themes) +menu(ZLE Functions) +menu(Other Functions) + endmenu() texinode(The Z Shell Manual)(Introduction)(Top)(Top) chapter(The Z Shell Manual) Index: Doc/Zsh/zftpsys.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -1,4 +1,4 @@ -texinode(Zftp Function System)()(Zsh Modules)(Top) +texinode(Zftp Function System)(User Contributions)(Zsh Modules)(Top) chapter(Zftp Function System) cindex(zftp function system) cindex(FTP, functions for using shell as client) Index: Doc/Zsh/zle.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -1115,7 +1115,7 @@ item(tt(run-help) (ESC-H ESC-h) (unbound) (unbound))( Push the buffer onto the buffer stack, and execute the command `tt(run-help) var(cmd)', where var(cmd) is the current -command. tt(run-help) is normally aliased to var(man). +command. tt(run-help) is normally aliased to tt(man). ) tindex(vi-set-buffer) item(tt(vi-set-buffer) (unbound) (") (unbound))( cvs diff: Diffing Etc cvs diff: Diffing Functions cvs diff: Diffing Functions/Misc cvs diff: Diffing Functions/Prompts Index: Functions/Prompts/promptinit =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -76,7 +76,7 @@ = Use prompt -h for help on specific themes.' = - getopts "chlps" opt + getopts "chlps:" opt case "$opt" in (h|p) setopt localtraps @@ -136,7 +136,8 @@ print " autoload -U promptinit" print " promptinit" print " prompt $*[2,-1]" - ;; + shift + ;& *) if [[ "$1" =3D=3D 'random' ]]; then local random_themes if (( $#* =3D=3D 1 )); then Index: Functions/Zle/history-search-end =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -8,13 +8,13 @@ # bindkey '...' history-beginning-search-backward-end # bindkey '...' history-beginning-search-forward-end = -integer ocursor=3D$CURSOR +integer cursor=3D$CURSOR mark=3D$MARK = if [[ $LASTWIDGET =3D history-beginning-search-*-end ]]; then - # Last widget called set $hbs_pos. - CURSOR=3D$hbs_pos + # Last widget called set $MARK. + CURSOR=3D$MARK else - hbs_pos=3D$CURSOR + MARK=3D$CURSOR fi = if zle .${WIDGET%-end}; then @@ -22,7 +22,8 @@ zle .end-of-line else # failure, restore position - CURSOR=3D$ocursor + CURSOR=3D$cursor + MARK=3D$mark return 1 fi # } Index: Functions/Zle/predict-on =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -29,20 +29,27 @@ zle -N magic-space insert-and-predict zle -N backward-delete-char delete-backward-and-predict zle -N delete-char-or-list delete-no-predict + zstyle -t :predict verbose && zle -M predict-on + return 0 } predict-off() { zle -A .self-insert self-insert zle -A .magic-space magic-space zle -A .backward-delete-char backward-delete-char + zstyle -t :predict verbose && zle -M predict-off + return 0 } insert-and-predict () { setopt localoptions noshwordsplit noksharrays - if [[ $LBUFFER =3D *$'\012'* ]] + + if [[ $LBUFFER =3D=3D *$'\012'* ]] || (( PENDING )) then - # Editing a multiline buffer, it's unlikely prediction is wanted + # Editing a multiline buffer or pasting in a chunk of text; + # it's unlikely prediction is wanted + zstyle -t ":predict" toggle && predict-off zle .$WIDGET "$@" return - elif [[ ${RBUFFER[1]} =3D ${KEYS[-1]} ]] + elif [[ ${RBUFFER[1]} =3D=3D ${KEYS[-1]} ]] then # Same as what's typed, just move on ((++CURSOR)) @@ -58,18 +65,15 @@ unsetopt automenu recexact integer curs=3D$CURSOR pos nchar=3D${#LBUFFER//[^${KEYS[-1]}]} local -a +h comppostfuncs - local crs curcontext=3D"${curcontext}" + local crs curcontext=3D"predict:${${curcontext:-:::}#*:}" = - [[ -z "$curcontext" ]] && curcontext=3D::: - curcontext=3D"predict:${curcontext#*:}" - comppostfuncs=3D( predict-limit-list ) zle complete-word # Decide where to leave the cursor. The dummy loop is used to # get out of that `case'. repeat 1 do - zstyle -s ":completion:${curcontext}:" cursor crs + zstyle -s ":predict" cursor crs case $crs in (complete) # At the place where the completion left it, if it is after @@ -92,27 +96,28 @@ done fi fi + else + zstyle -t ":predict" toggle && predict-off fi fi return 0 } delete-backward-and-predict() { - if [[ -n "$LBUFFER" ]] + if (( $#LBUFFER > 1 )) then setopt localoptions noshwordsplit noksharrays - if [[ $LBUFFER =3D *$'\012'* ]] then - # Editing a multiline buffer, it's unlikely prediction is wanted - zle .$WIDGET "$@" - # If the last widget was e.g. a motion, then probably the intent is + # When editing a multiline buffer, it's unlikely prediction is wante= d; + # or if the last widget was e.g. a motion, then probably the intent = is # to actually edit the line, not change the search prefix. - elif [[ $LASTWIDGET =3D=3D (self-insert|magic-space|backward-delete-= char) ]] + if [[ $LBUFFER =3D *$'\012'* || + $LASTWIDGET !=3D (self-insert|magic-space|backward-delete-char) ]] then + zstyle -t ":predict" toggle && predict-off + LBUFFER=3D"$LBUFFER[1,-2]" + else ((--CURSOR)) zle .history-beginning-search-forward || RBUFFER=3D"" return 0 - else - # Depending on preference, you might call "predict-off" here. - LBUFFER=3D"$LBUFFER[1,-2]" fi fi } @@ -130,7 +135,7 @@ compstate[nmatches] > compstate[list_max] ) )) then compstate[list]=3D'' - elif zstyle -t ":completion:predict::::" list always + elif zstyle -t ":predict" list always then compstate[list]=3D'force list' fi Index: Doc/Zsh/contrib.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -0,0 +1,782 @@ +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 th= e +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 alia= s +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 manu= al +to produce a separate help file for each shell builtin and for many othe= r +shell features as well. The autoloadable tt(run-help) function, found i= n +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=3D~/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 (se= e +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) + +If you frequently edit your zsh functions, or periodically update your z= sh +installation to track the latest developments, you may find that functio= n +digests compiled with the tt(zcompile) builtin are frequently out of dat= e +with respect to the function source files. This is not usually a proble= m, +because zsh always looks for the newest file when loading a function, bu= t +it may cause slower shell startup and function loading. + +The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), c= an +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) = =2E.. ])( +This tries to find wordcode files and automatically re-compile them if a= t +least one of the original files is newer than the wordcode file. This +works only if the names stored in the wordcode files are full paths or a= re +relative to the directory that contains the wordcode file. + +In the first form, each var(name) is the name of a wordcode file or a +directori containing wordcode files that should be checked. If no +arguments are given, the directories and wordcode files in $fpath are +used. + +When tt(-t) is given, no compilation is performed, but a return status o= f +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 wordcode fil= es +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 interepted 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 o= r +if it is older than tt(~/.zshrc). The wordcode file will be marked for +reading instead of mapping. The same is done for tt(~/.zcompdump) and +tt(~/.zcompdump.zwc), but this wordcode 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 diges= ts +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 writ= e +permission to the directories: + +example(for ((i=3D1; i <=3D $#fpath; ++i)); do + dir=3D$fpath[i] + zwc=3D${dir:t}.zwc + if [[ $dir =3D=3D (.|..) || $dir =3D=3D (.|..)/* ]]; then + continue + fi + files=3D($dir/*(N-.)) + if [[ -w $dir:h && -n $files ]]; then + files=3D(${${(M)files%/*/*}#/}) + if ( cd $dir:h && + zrecompile -p -U -z $zwc $files ); then + fpath[i]=3D$fpath[i].zwc + fi + fi +done) + +The tt(-U) and tt(-z) options are appropriate for functions in the defau= lt +zsh installation tt(fpath); you may need to use different options for yo= ur +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(Dumping Shell State) + +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 t= he +developers. Also, as the output can be voluminous, it's best to wait fo= r +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 keyma= p +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= =2E +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); us= e +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= =2E +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)'= =2E +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 a= s +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=3D(~/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 se= e +a list. The special var(theme) `tt(random)' selects at random one of th= e +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 a= ny.) +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 Contributio= ns) +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(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 curso= r +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 th= e +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 +paramter 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 inserte= d +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 backwa= rd +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 foun= d. +In fact, you often don't even need to use tt(predict-off), because if th= e +line doesn't match something in the history, adding a key performs +standard completion, and then inserts itself if no completions were foun= d. +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), yo= u +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 o= f +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-c= har) +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) +) +enditem() + +subsect(Styles) + +The behavior of several of the above widgets can be controlled by the us= e +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, completion style) +item(tt(break-keys))( +This style is used by the tt(incremental-complete-word) widget. Its valu= e +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. +) +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 completio= n +and for these widgets. For example, to use completion, approximation an= d +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) +) +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, completion 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= =2E +This is done if the value of this style is the string tt(always). In th= is +case the context is `tt(:predict)' (em(not) `tt(:completion:predict)'). +) +kindex(prompt, completion 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() +) +kindex(stop-keys, completion style) +item(tt(stop-keys))( +This style is used by the tt(incremental-complete-word) widget. Its val= ue +is treated similarly to the one for the tt(break-keys) style. 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, completion 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, completion 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 sta= te +is toggled. This is most useful in combination with the tt(toggle) styl= e. +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, cya= n, +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 us= ed +to negate attributes: none (reset all attributes to the defaults), norma= l +(neither bold nor faint), no-standout, no-underline, no-blink, and +no-reverse. + +Some terminals do not support all combinations of colors and intensities= =2E + +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. T= he +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 t= he +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 s= et +the corresponding foreground text properties. The tt(fg) sequences chan= ge +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 s= et +the corresponding background properties. The tt(bg) sequences change th= e +color without changing the eight intensity attributes. +) +enditem() + +In addition, the scalar parameters tt(reset_color) and tt(bold_color) ar= e +set to the ANSI terminal escapes that turn off all attributes and turn o= n +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 wi= th +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 i= n +the two strings with leading non-number parts ignored. If one string ha= s +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. 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 us= e +the function-based completion system). Completion styles may be set wit= h +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 rebind= s +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, an= d +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 o= f +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 w= ay +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 ne= ed +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). +) +findex(zmv) +item(tt(zmv) [ tt(-finqQsvw) ] [ -C | -L | -M | -p var(program) ] [ -o v= ar(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 gav= e +the same result, the destination was an existing regular file and tt(-f)= +was not given) causes the entire function to abort without doing anythin= g. + +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 use= r +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 o= f +the name of the function.) +sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) o= r +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 usua= l, +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 sty= le. +) +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 doe= s +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, respectivel= y. +The usual expansions for the tt(PS1) and tt(RPS1) parameters may be used= +(see +ifzman(zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion))\ +). +) +enditem() Index: Doc/zshcontrib.yo =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -0,0 +1,3 @@ +manpage(ZSHCONTRIB)(1)(date())(zsh version()) +manpagename(zshcontrib)(user contributions to zsh) +includefile(Zsh/contrib.yo)=01 -- = Bart Schaefer Brass Lantern Enterprises http://www.well.com/user/barts http://www.brasslantern.com Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net = =