diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/.distfiles | 1 | ||||
| -rw-r--r-- | Doc/Makefile.in | 5 | ||||
| -rw-r--r-- | Doc/Zsh/builtins.yo | 39 | ||||
| -rw-r--r-- | Doc/Zsh/cond.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 34 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 19 | ||||
| -rw-r--r-- | Doc/Zsh/options.yo | 5 | ||||
| -rw-r--r-- | Doc/Zsh/params.yo | 32 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 37 | ||||
| -rw-r--r-- | Doc/intro.ms | 30 |
10 files changed, 164 insertions, 43 deletions
diff --git a/Doc/.distfiles b/Doc/.distfiles index 07263317c..b639949d3 100644 --- a/Doc/.distfiles +++ b/Doc/.distfiles @@ -18,4 +18,5 @@ DISTFILES_DOC=' *.html zsh.dvi zsh.pdf + intro.pdf ' diff --git a/Doc/Makefile.in b/Doc/Makefile.in index d30149da0..df3e1410b 100644 --- a/Doc/Makefile.in +++ b/Doc/Makefile.in @@ -94,7 +94,7 @@ dvi: zsh.dvi zsh.dvi: $(sdir)/zsh.texi $(TEXI2DVI) $(sdir)/zsh.texi -pdf: zsh.pdf +pdf: zsh.pdf intro.pdf .PHONY: pdf zsh.pdf: $(sdir)/zsh.texi @@ -104,6 +104,9 @@ zsh.pdf: $(sdir)/zsh.texi PDFTEX=$(PDFETEX) $(TEXI2DVI) --pdf $(sdir)/zsh.texi; \ fi +intro.pdf: $(sdir)/intro.ms + pdfroff -ms $(sdir)/intro.ms >intro.pdf + texi: $(sdir)/zsh.texi .PHONY: texi diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 5d717479a..98c470a54 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -348,7 +348,7 @@ cindex(compatibility, csh) cindex(sh, compatibility) cindex(ksh, compatibility) cindex(csh, compatibility) -item(tt(emulate) [ tt(-LR) ] [ {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)} [ tt(-c) tt(arg) ] ])( +item(tt(emulate) [ tt(-LR) ] [ {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)} [ var(flags) ... ] ])( Without any argument print current emulation mode. With single argument set up zsh options to emulate the specified shell @@ -359,33 +359,48 @@ will be used as a default; more precisely, the tests performed on the argument are the same as those used to determine the emulation at startup based on the shell name, see ifzman(\ -the section `Compatibility' in zmanref(zshmisc) +the section COMPATIBILITY in zmanref(zsh) )\ ifnzman(\ noderef(Compatibility) )\ . -If the tt(-R) option is given, all options +If the tt(emulate) command occurs inside a function that has been +marked for execution tracing with tt(functions -t) then the tt(xtrace) +option will be turned on regardless of emulation mode or other options. +Note that code executed inside the function by the tt(.), tt(source), or +tt(eval) commands is not considered to be running directly from the +function, hence does not provoke this behaviour. + +If the tt(-R) switch is given, all settable options are reset to their default value corresponding to the specified emulation mode, except for certain options describing the interactive environment; otherwise, only those options likely to cause portability -problems in scripts and functions are altered. If the tt(-L) option is given, +problems in scripts and functions are altered. If the tt(-L) switch is given, the options tt(LOCAL_OPTIONS) and tt(LOCAL_TRAPS) will be set as well, causing the effects of the tt(emulate) command and any tt(setopt) and tt(trap) commands to be local to the immediately surrounding shell function, if any; normally these options are turned off in all emulation -modes except tt(ksh). The tt(-L) and tt(-c) are mutually exclusive. - -If tt(-c) tt(arg) is given, evaluate tt(arg) while the requested -emulation is temporarily in effect. The emulation and all options will -be restored to their original values before tt(emulate) returns. The -tt(-R) flag may be used. +modes except tt(ksh). The tt(-L) switch is mutually exclusive with the +use of tt(-c) in var(flags). + +The var(flags) may be any of the invocation-time flags described in +ifnzman(noderef(Invocation))\ +ifzman(the section INVOCATION in zmanref(zsh)), +except that `tt(-o EMACS)' and `tt(-o VI)' may not be used. Flags such +as `tt(+r)'/`tt(+o RESTRICTED)' may be prohibited in some circumstances. +If tt(-c) var(arg) appears in var(flags), var(arg) is evaluated while the +requested emulation is temporarily in effect. In this case the emulation +mode and all options are restored to their previous values before +tt(emulate) returns. The tt(-R) switch may precede the name of the shell +to emulate; note this has a meaning distinct from including tt(-R) in +var(flags). Use of tt(-c) enables `sticky' emulation mode for functions defined within the evaluated expression: the emulation mode is associated thereafter with the function so that whenever the function is executed -the emulation (respecting the tt(-R) flag, if present) and all +the emulation (respecting the tt(-R) switch, if present) and all options are set before entry to the function, and restored after exit. If the function is called when the sticky emulation is already in effect, either within an `tt(emulate) var(shell) tt(-c)' expression or @@ -427,7 +442,7 @@ within sticky emulation.) sitem(3.)(No special handling is provided for functions marked for tt(autoload) nor for functions present in wordcode created by the tt(zcompile) command.) -sitem(4.)(The presence or absence of the tt(-R) flag to tt(emulate) +sitem(4.)(The presence or absence of the tt(-R) switch to tt(emulate) corresponds to different sticky emulation modes, so for example `tt(emulate sh -c)', `tt(emulate -R sh -c)' and `tt(emulate csh -c)' are treated as three distinct sticky emulations.) diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo index 71971b4b3..9f8a7d820 100644 --- a/Doc/Zsh/cond.yo +++ b/Doc/Zsh/cond.yo @@ -151,6 +151,11 @@ based on ASCII value of their characters. ) item(var(exp1) tt(-eq) var(exp2))( true if var(exp1) is numerically equal to var(exp2). +Note that for purely numeric comparisons use of the +tt(LPAR()LPAR())var(...)tt(RPAR()RPAR()) builtin described in +ifzman(the section `ARITHMETIC EVALUATION')\ +ifnzman(noderef(Arithmetic Evaluation)) is more convenient than +conditional expressions. ) item(var(exp1) tt(-ne) var(exp2))( true if var(exp1) is numerically not equal to var(exp2). diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index aee0bd7f4..139a68150 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -999,8 +999,8 @@ endsitem() In tt(patch-format) and tt(nopatch-format) these replacements are done: startsitem() -sitem(tt(%p))(The name of the top-most applied patch.) -sitem(tt(%u))(The number of unapplied patches.) +sitem(tt(%p))(The name of the top-most applied patch (tt(applied-string)).) +sitem(tt(%u))(The number of unapplied patches (tt(unapplied-string)).) sitem(tt(%n))(The number of applied patches.) sitem(tt(%c))(The number of unapplied patches.) sitem(tt(%g))(The names of active tt(mq) guards (tt(hg) backend).) @@ -1734,6 +1734,16 @@ context is examined and if it contains the string tt(back), the word before the cursor is considered, else the word after cursor is considered. Some examples are given below. +The style tt(skip-whitespace-first) is only used with the +tt(forward-word) widget. If it is set to true, then tt(forward-word) +skips any non-word-characters, followed by any non-word-characters: +this is similar to the behaviour of other word-orientated widgets, +and also that used by other editors, however it differs from the +standard zsh behaviour. When using tt(select-word-style) the widget +is set in the context tt(:zle:*) to tt(true) if the word style is +tt(bash) and tt(false) otherwise. It may be overridden by setting it in +the more specific context tt(:zle:forward-word*). + Here are some examples of use of the styles, actually taken from the simplified interface in tt(select-word-style): @@ -3463,11 +3473,11 @@ game. ) findex(zargs) item(tt(zargs) [ var(option) ... tt(-)tt(-) ] [ var(input) ... ] [ tt(-)tt(-) var(command) [ var(arg) ... ] ])( -This function works like GNU xargs, except that instead of reading lines -of arguments from the standard input, it takes them from the command line. -This is useful because zsh, especially with recursive glob operators, -often can construct a command line for a shell function that is longer -than can be accepted by an external command. +This function has a similar purpose to GNU xargs. Instead of +reading lines of arguments from the standard input, it takes them from +the command line. This is useful because zsh, especially with recursive +glob operators, often can construct a command line for a shell function +that is longer than can be accepted by an external command. The var(option) list represents options of the tt(zargs) command itself, which are the same as those of tt(xargs). The var(input) list is the @@ -3501,7 +3511,15 @@ example(zargs -e.. -- **/*(.) .. ls -l) This is a good choice in that example because no plain file can be named `tt(..)', but the best end-marker depends on the circumstances. -For details of the other tt(zargs) options, see zmanref(xargs) or run +The options tt(-i), tt(-I), tt(-l), tt(-L), and tt(-n) differ slightly +from their usage in tt(xargs). There are no input lines for tt(zargs) to +count, so tt(-l) and tt(-L) count through the var(input) list, and tt(-n) +counts the number of arguments passed to each execution of var(command), +em(including) any var(arg) list. Also, any time tt(-i) or tt(-I) is used, +each var(input) is processed separately as if by `tt(-L) tt(1)'. + +For details of the other tt(zargs) options, see zmanref(xargs) (but note +the difference in function between tt(zargs) and tt(xargs)) or run tt(zargs) with the tt(-)tt(-help) option. ) findex(zed) diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index 25c44f331..8afd92532 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -604,6 +604,19 @@ If var(name) is an array the matching array elements are removed (use the `tt((M))' flag to remove the non-matched elements). ) +item(tt(${)var(name)tt(:|)var(arrayname)tt(}))( +If var(arrayname) is the name (N.B., not contents) of an array +variable, then any elements contained in var(arrayname) are removed +from the substitution of var(name). If the substitution is scalar, +either because var(name) is a scalar variable or the expression is +quoted, the elements of var(arrayname) are instead tested against the +entire expression. +) +item(tt(${)var(name)tt(:*)var(arrayname)tt(}))( +Similar to the preceding subsitution, but in the opposite sense, +so that entries present in both the original substitution and as +elements of var(arrayname) are retained and others removed. +) xitem(tt(${)var(name)tt(:)var(offset)tt(})) item(tt(${)var(name)tt(:)var(offset)tt(:)var(length)tt(}))( This syntax gives effects similar to parameter subscripting @@ -1954,6 +1967,9 @@ item(tt(I))( Case sensitive: locally negates the effect of tt(i) or tt(l) from that point on. ) +vindex(match) +vindex(mbegin) +vindex(mend) item(tt(b))( Activate backreferences for parenthesised groups in the pattern; this does not work in filename generation. When a pattern with a set of @@ -2022,6 +2038,9 @@ matches; tt(LPAR()#c,)var(M)tt(RPAR()) is equivalent to specifying var(N) as 0; tt(LPAR()#c)var(N)tt(,RPAR()) specifies that there is no maximum limit on the number of matches. ) +vindex(MATCH) +vindex(MBEGIN) +vindex(MEND) item(tt(m))( Set references to the match data for the entire string matched; this is similar to backreferencing and does not work in filename generation. The diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index dd237c0ef..3114ecc05 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -313,8 +313,9 @@ pindex(NO_HASH_LIST_ALL) pindex(HASHLISTALL) pindex(NOHASHLISTALL) item(tt(HASH_LIST_ALL) <D>)( -Whenever a command completion is attempted, make sure the entire -command path is hashed first. This makes the first completion slower. +Whenever a command completion or spelling correction is attempted, make +sure the entire command path is hashed first. This makes the first +completion slower but avoids false reports of spelling errors. ) pindex(LIST_AMBIGUOUS) pindex(NO_LIST_AMBIGUOUS) diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index e9a3c722d..5991921f8 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -226,6 +226,7 @@ example (assuming the option tt(KSH_ARRAYS) is not in effect): example([[ ${array[(i)pattern]} -le ${#array} ]]) If tt(KSH_ARRAYS) is in effect, the tt(-le) should be replaced by tt(-lt). +) item(tt(R))( Like `tt(r)', but gives the last match. For associative arrays, gives all possible matches. May be used for assigning to ordinary array @@ -244,7 +245,6 @@ required; using a parameter to hold the key has the desired effect: example(key2='original key' print ${array[(Re)$key2]}) ) -) item(tt(i))( Like `tt(r)', but gives the index of the match instead; this may not be combined with a second argument. On the left side of an assignment, @@ -1003,6 +1003,10 @@ and replaces the tt(SUNKEYBOARDHACK) option which did this for backquotes only. Should the chosen character be one of singlequote, doublequote or backquote, there must also be an odd number of them on the command line for the last one to be removed. + +For backward compabitility, if the tt(SUNKEYBOARDHACK) option is +explicitly set, the value of tt(KEYBOARD_HACK) reverts to backquote. +If the option is explicitly unset, this variable is set to empty. ) vindex(KEYTIMEOUT) item(tt(KEYTIMEOUT))( @@ -1099,6 +1103,22 @@ whose value is not used by the shell. The tt(manpath) array can be useful, however, since setting it also sets tt(MANPATH), and vice versa. ) +xitem(tt(match)) +xitem(tt(mbegin)) +item(tt(mend))( +Arrays set by the shell when the tt(b) globbing flag is used in pattern +matches. See the subsection em(Globbing flags) in +ifzman(the documentation for em(Filename Generation) in zmanref(zshexpn))\ +ifnzman(noderef(Filename Generation)). +) +xitem(tt(MATCH)) +xitem(tt(MBEGIN)) +item(tt(MEND))( +Set by the shell when the tt(m) globbing flag is used in pattern +matches. See the subsection em(Globbing flags) in +ifzman(the documentation for em(Filename Generation) in zmanref(zshexpn))\ +ifnzman(noderef(Filename Generation)). +) vindex(module_path) vindex(MODULE_PATH) item(tt(module_path) <S> <Z> (tt(MODULE_PATH) <S>))( @@ -1283,7 +1303,7 @@ the workaround `tt(TERM=$TERM)' unnecessary. vindex(TIMEFMT) item(tt(TIMEFMT))( The format of process time reports with the tt(time) keyword. -The default is `tt(%E real %U user %S system %P %J)'. +The default is `tt(%J %U user %S system %P cpu %*E total)'. Recognizes the following escape sequences, although not all may be available on all systems, and some that are available may not be useful: @@ -1296,12 +1316,12 @@ sitem(tt(%E))(Elapsed time in seconds.) sitem(tt(%P))(The CPU percentage, computed as (100*tt(%U)PLUS()tt(%S))/tt(%E).) sitem(tt(%W))(Number of times the process was swapped.) -sitem(tt(%X))(The average amount in (shared) text space used in Kbytes.) +sitem(tt(%X))(The average amount in (shared) text space used in kilobytes.) sitem(tt(%D))(The average amount in (unshared) data/stack space used in -Kbytes.) -sitem(tt(%K))(The total space used (%X+%D) in Kbytes.) +kilobytes.) +sitem(tt(%K))(The total space used (%X+%D) in kilobytes.) sitem(tt(%M))(The maximum memory the process had in use at any time in -Kbytes.) +megabytes.) sitem(tt(%F))(The number of major page faults (page needed to be brought from disk).) sitem(tt(%R))(The number of minor page faults.) diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index d3624b1ce..3e8c25a90 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -877,6 +877,12 @@ any predisplay string should be highlighted in bold. Note that the effect of tt(region_highlight) is not saved and disappears as soon as the line is accepted. ) +vindex(UNDO_CHANGE_NO) +item(tt(UNDO_CHANGE_NO) (integer))( +A number representing the state of the undo history. The only use +of this is passing as an argument to the tt(undo) widget in order to +undo back to the recorded point. Read-only. +) vindex(WIDGET) item(tt(WIDGET) (scalar))( The name of the widget currently being executed; read-only. @@ -902,11 +908,20 @@ item(tt(ZLE_STATE) (scalar))( Contains a set of space-separated words that describe the current tt(zle) state. -Currently, the only state shown is the insert mode as set by the -tt(overwrite-mode) or tt(vi-replace) widgets. The string contains -`tt(insert)' if characters to be inserted on the command line move existing -characters to the right, `tt(overwrite)' if characters to be inserted -overwrite existing characters. +Currently, the states shown are the insert mode as set by the +tt(overwrite-mode) or tt(vi-replace) widgets and whether history commands +will visit imported entries as controlled by the set-local-history widget. +The string contains `tt(insert)' if characters to be inserted on the +command line move existing characters to the right or `tt(overwrite)' +if characters to be inserted overwrite existing characters. It contains +`tt(localhistory)' if only local history commands will be visited or +`tt(globalhistory)' if imported history commands will also be visited. + +The substrings are sorted in alphabetical order so that if you want to +test for two specific substrings in a future-proof way, you can do match +by doing: + +example(if [[ $ZLE_STATE == *insert*globalhistory* ]]; then ...; fi) ) enditem() @@ -1464,6 +1479,13 @@ Search forward in the history for a line beginning with the current line up to the cursor. This leaves the cursor in its original position. ) +tindex(set-local-history) +item(tt(set-local-history))( +By default, history movement commands visit the imported lines as well as +the local lines. This widget lets you toggle this on and off, or set it with +the numeric argument. Zero for both local and imported lines and nonzero for +only local lines. +) enditem() texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets) subsect(Modifying Text) @@ -2164,7 +2186,10 @@ command is typed. By default it beeps. ) tindex(undo) item(tt(undo) (^_ ^Xu ^X^U) (unbound) (unbound))( -Incrementally undo the last text modification. +Incrementally undo the last text modification. When called from a +user-defined widget, takes an optional argument indicating a previous state +of the undo history as returned by the tt(UNDO_CHANGE_NO) variable; +modifications are undone until that state is reached. ) tindex(redo) item(tt(redo))( diff --git a/Doc/intro.ms b/Doc/intro.ms index f4f7062d0..fcca33dd8 100644 --- a/Doc/intro.ms +++ b/Doc/intro.ms @@ -135,7 +135,7 @@ run303 run123\0\0run2 %\0ls\0run<300-> run303 -%\0ls\0run<> +%\0ls\0run<-> run123\0\0run2\0\0\0\0run234\0\0run240\0\0run303 .De The \fINUMERICGLOBSORT\fP option will sort files with numbers @@ -143,7 +143,7 @@ according to the number. This will not work with \fCls\fP as it resorts its arguments: .Ds %\0setopt\0numericglobsort -%\0echo\0run<> +%\0echo\0run<-> run2\0run123\0run234\0run240\0run303 .De Grouping is possible: @@ -692,12 +692,12 @@ by setting a few more options and parameters: 2\0\0\0\0\0\0\0/usr/bin 3\0\0\0\0\0\0\0/usr 4\0\0\0\0\0\0\0~ -/tmp>\0ls\0=2/df +/tmp>\0ls\0~2/df /usr/bin/df /tmp>\0cd\0-4 ~> .De -Note that \fC=2\fP expanded to the second directory in the +Note that \fC~2\fP expanded to the second directory in the history list, and that \fCcd -3\fP recalled the third directory in the list. .PP @@ -2282,11 +2282,20 @@ The same is true of \fBCDPATH\fP and \fBcdpath\fP: In general, predefined parameters with names in all lowercase are arrays; assignments to them take the form: .Ds -\fIname\fR\fC=(\fR\0\fIelem\fR\0...\\0\fC)\fR +\fIname\fR\fC=(\fR\0\fIelem\fR\0...\0\fC)\fR .De Predefined parameters with names in all uppercase are strings. If there is both an array and a string version of the same parameter, the -string version is a colon-separated list, like \fBPATH\fP. +string version is a colon-separated list, like \fBPATH\fP. You can use +.Ds +%\0typeset\0-T\0FOO\0foo +.De +to create more of these yourself. +.Ds +%\0foo=(\0a\0b\0c\0) +%\0echo\0$FOO +a:b:c +.De .PP \fBHISTFILE\fP is the name of the history file, where the history is saved when a shell exits. @@ -2314,7 +2323,7 @@ exit \0\0\029\0\0HISTSIZE=3 \0\0\030\0\0history .De -If you have several incantations of \fBzsh\fP running at the same +If you have several instances of \fBzsh\fP running at the same time, like when using the X window system, it might be preferable to append the history of each shell to a file when a shell exits instead of overwriting the old contents of the file. You can get this @@ -2432,6 +2441,7 @@ and command line while leaving command output unhighlighted, try this: %\0POSTEDIT=`echotc\0se` %\0PROMPT='%S%%\0' .De +This trick is mostly superceded by the zle_highlight array parameter. .Sh "Login/logout watching" .PP You can specify login or logout events to monitor @@ -2595,10 +2605,14 @@ in csh. zsh:\0unmatched\0' .De \fIGLOBDOTS\fP lets files beginning with a \fC.\fP be matched without -explicitly specifying the dot. +explicitly specifying the dot. This can also be specified for a particular +pattern by appending (D) to it. .Ds %\0ls\0-d\0*x* Mailboxes +%\0ls\0-d\0*x*(D) +\&.exrc\0\0\0\0\0\0\0\0\0.pnewsexpert\0\0.xserverrc +\&.mushexpert\0\0\0.xinitrc\0\0\0\0\0\0Mailboxes %\0setopt\0globdots %\0ls\0-d\0*x* \&.exrc\0\0\0\0\0\0\0\0\0.pnewsexpert\0\0.xserverrc |