diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 37 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/contrib.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/expn.yo | 13 | ||||
| -rw-r--r-- | Doc/Zsh/grammar.yo | 9 | ||||
| -rw-r--r-- | Doc/Zsh/mod_datetime.yo | 8 | ||||
| -rw-r--r-- | Doc/Zsh/mod_nearcolor.yo | 36 | ||||
| -rw-r--r-- | Doc/Zsh/mod_zpty.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/redirect.yo | 14 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 20 |
10 files changed, 119 insertions, 29 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index f460e48a5..fd29ca3a5 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -1332,7 +1332,7 @@ If any of `tt(-m)', `tt(-o)' or `tt(-O)' are used in combination with case of `tt(-m)') then nothing is printed. ) findex(printf) -item(tt(printf) [ -v var(name) ] var(format) [ var(arg) ... ])( +item(tt(printf) [ tt(-v) var(name) ] var(format) [ var(arg) ... ])( Print the arguments according to the format specification. Formatting rules are the same as used in C. The same escape sequences as for tt(echo) are recognised in the format. All C conversion specifications ending in @@ -2029,6 +2029,9 @@ scalar version causes a split on all separators (which cannot be quoted). It is possible to apply tt(-T) to two previously tied variables but with a different separator character, in which case the variables remain joined as before but the separator is changed. + +When an existing scalar is tied to a new array, the value of the scalar +is preserved but no attribute other than export will be preserved. ) enditem() @@ -2076,12 +2079,12 @@ flag. ) item(tt(-U))( For arrays (but not for associative arrays), keep only the first -occurrence of each duplicated value. This may also be set for -colon-separated special parameters like tt(PATH) or tt(FIGNORE), etc. -Note the flag takes effect on assignment, and the type of the -variable being assigned to is determinative; for variables with -shared values it is therefore recommended to set the flag for -all interfaces, e.g. `tt(typeset -U PATH path)'. +occurrence of each duplicated value. This may also be set for tied +parameters (see tt(-T)) or colon-separated special parameters like +tt(PATH) or tt(FIGNORE), etc. Note the flag takes effect on assignment, +and the type of the variable being assigned to is determinative; for +variables with shared values it is therefore recommended to set the flag +for all interfaces, e.g. `tt(typeset -U PATH path)'. This flag has a different meaning when used with tt(-f); see below. ) @@ -2174,9 +2177,17 @@ be turned off. If the tt(POSIX_BUILTINS) option is set, the readonly attribute is more restrictive: unset variables can be marked readonly and cannot then be set; furthermore, the readonly attribute cannot be removed from any -variable. Note that in zsh (unlike other shells) it is still possible -to create a local variable of the same name as this is considered a -different variable (though this variable, too, can be marked readonly). +variable. + +It is still possible to change other attributes of the variable though, +some of which like tt(-U) or tt(-Z) would affect the value. More generally, +the readonly attribute should not be relied on as a security mechanism. + +Note that in zsh (like in pdksh but unlike most other shells) it is +still possible to create a local variable of the same name as this is +considered a different variable (though this variable, too, can be marked +readonly). Special variables that have been made readonly retain their value +and readonly attribute when made local. ) item(tt(-t))( Tags the named parameters. Tags have no special meaning to the shell. @@ -2373,6 +2384,12 @@ item(tt(whence) [ tt(-vcwfpamsS) ] [ tt(-x) var(num) ] var(name) ...)( For each var(name), indicate how it would be interpreted if used as a command name. +If var(name) is not an alias, built-in command, external command, shell +function, hashed command, or a reserved word, the exit status shall be +non-zero, and DASH()- if tt(-v), tt(-c), or tt(-w) was passed DASH()- a message +will be written to standard output. (This is different from other shells that +write that message to standard error.) + tt(whence) is most useful when var(name) is only the last path component of a command, i.e. does not include a `tt(/)'; in particular, pattern matching only succeeds if just the non-directory component of the command is diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 65f596752..a5a9e5b5d 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -489,7 +489,11 @@ The parameter tt($_compskip) may be set by any function defined for a pattern context. If it is set to a value containing the substring `tt(patterns)' none of the pattern-functions will be called; if it is set to a value containing the substring `tt(all)', no other function -will be called. +will be called. Setting tt($_compskip) in this manner is of particular +utility when using the tt(-p) option, as otherwise the dispatcher will +move on to additional functions (likely the default one) after calling +the pattern-context one, which can mangle the display of completion +possibilities if not handled properly. The form with tt(-k) defines a widget with the same name as the var(function) that will be called for each of the var(key-sequence)s; this is like the diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 0c2ba484c..d32ba018d 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -1668,7 +1668,7 @@ tt(mq)) backend and in tt(quilt) support when the tt(unapplied-string) is generated; the tt(get-unapplied) style must be true. This hook gets the names of all unapplied patches which tt(vcs_info) -collected so far in the opposite order, which mean that the first argument is +collected so far in order, which means that the first argument is the patch next-in-line to be applied and so forth. When setting tt(ret) to non-zero, the string in diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo index c79109700..a212d742d 100644 --- a/Doc/Zsh/expn.yo +++ b/Doc/Zsh/expn.yo @@ -1683,10 +1683,17 @@ any trailing newlines deleted. If the substitution is not enclosed in double quotes, the output is broken into words using the tt(IFS) parameter. vindex(IFS, use of) + The substitution `tt($LPAR()cat) var(foo)tt(RPAR())' may be replaced -by the equivalent but faster `tt($LPAR()<)var(foo)tt(RPAR())'. -In either case, if the option tt(GLOB_SUBST) is set, -the output is eligible for filename generation. +by the faster `tt($LPAR()<)var(foo)tt(RPAR())'. In this case var(foo) +undergoes single word shell expansions (em(parameter expansion), +em(command substitution) and em(arithmetic expansion)), but not +filename generation. + +If the option tt(GLOB_SUBST) is set, the result of any unquoted command +substitution, including the special form just mentioned, is eligible for +filename generation. + texinode(Arithmetic Expansion)(Brace Expansion)(Command Substitution)(Expansion) sect(Arithmetic Expansion) cindex(arithmetic expansion) diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo index d2c7cd29c..d30c9d2d7 100644 --- a/Doc/Zsh/grammar.yo +++ b/Doc/Zsh/grammar.yo @@ -183,12 +183,15 @@ findex(for) cindex(for loops) cindex(loops, for) item(tt(for) var(name) ... [ tt(in) var(word) ... ] var(term) tt(do) var(list) tt(done))( -where var(term) is at least one newline or tt(;). Expand the list of var(word)s, and set the parameter -var(name) to each of them in turn, executing -var(list) each time. If the tt(in) var(word) is omitted, +var(name) to each of them in turn, executing var(list) +each time. If the `tt(in) var(word)' is omitted, use the positional parameters instead of the var(word)s. +The var(term) consists of one or more newline or tt(;) +which terminate the var(word)s, and are optional when the +`tt(in) var(word)' is omitted. + More than one parameter var(name) can appear before the list of var(word)s. If var(N) var(name)s are given, then on each execution of the loop the next var(N) var(word)s are assigned to the corresponding diff --git a/Doc/Zsh/mod_datetime.yo b/Doc/Zsh/mod_datetime.yo index 27bc78157..da65a9bbd 100644 --- a/Doc/Zsh/mod_datetime.yo +++ b/Doc/Zsh/mod_datetime.yo @@ -6,9 +6,13 @@ The tt(zsh/datetime) module makes available one builtin command: startitem() findex(strftime) cindex(date string, printing) -xitem(tt(strftime) [ tt(-s) var(scalar) ] var(format) var(epochtime) ) +xitem(tt(strftime) [ tt(-s) var(scalar) ] var(format) [ var(epochtime) [ var(nanoseconds) ] ] ) item(tt(strftime) tt(-r) [ tt(-q) ] [ tt(-s) var(scalar) ] var(format) var(timestring) )( -Output the date denoted by var(epochtime) in the var(format) specified. +Output the date in the var(format) specified. With no var(epochtime), the +current system date/time is used; optionally, var(epochtime) may be used to +specify the number of seconds since the epoch, and var(nanoseconds) may +additionally be used to specify the number of nanoseconds past the second +(otherwise that number is assumed to be 0). See manref(strftime)(3) for details. The zsh extensions described in ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ ifnzman(noderef(Prompt Expansion)) are also available. diff --git a/Doc/Zsh/mod_nearcolor.yo b/Doc/Zsh/mod_nearcolor.yo new file mode 100644 index 000000000..df7771397 --- /dev/null +++ b/Doc/Zsh/mod_nearcolor.yo @@ -0,0 +1,36 @@ +COMMENT(!MOD!zsh/nearcolor +Map colours to the nearest colour in the available palette. +!MOD!) +The tt(zsh/nearcolor) module replaces colours specified as hex triplets +with the nearest colour in the 88 or 256 colour palettes that are widely +used by terminal emulators. By default, 24-bit true colour escape codes +are generated when colours are specified using hex triplets. These are +not supported by all terminals. The purpose of this module is to make +it easier to define colour preferences in a form that can work across a +range of terminal emulators. + +Aside from the default colour, the ANSI standard for terminal escape +codes provides for eight colours. The bright attribute brings this to +sixteen. These basic colours are commonly used in terminal applications +due to being widely supported. Expanded 88 and 256 colour palettes are +also common and, while the first sixteen colours vary somewhat between +terminals and configurations, these add a generally consistent and +predictable set of colours. + +In order to use the tt(zsh/nearcolor) module, it only needs to be +loaded. Thereafter, whenever a colour is specified using a hex triplet, +it will be compared against each of the available colours and the +closest will be selected. The first sixteen colours are never matched in +this process due to being unpredictable. + +It isn't possible to reliably detect support for true colour in the +terminal emulator. It is therefore recommended to be selective in +loading the tt(zsh/nearcolor) module. For example, the following +checks the tt(COLORTERM) environment variable: + +example([[ $COLORTERM = *LPAR()24bit|truecolor+RPAR()* ]] || \ + zmodload zsh/nearcolor) + +Note that some terminals accept the true color escape codes but map +them internally to a more limited palette in a similar manner to the +tt(zsh/nearcolor) module. diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo index 44b375a3c..6f20c4b75 100644 --- a/Doc/Zsh/mod_zpty.yo +++ b/Doc/Zsh/mod_zpty.yo @@ -41,7 +41,8 @@ em(not) given, a newline is added at the end. If no var(string) is provided, the standard input is copied to the pseudo-terminal; this may stop before copying the full input if the -pseudo-terminal is non-blocking. +pseudo-terminal is non-blocking. The exact input is always copied: +the tt(-n) option is not applied. Note that the command under the pseudo-terminal sees this input as if it were typed, so beware when sending special tty driver characters such as diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo index c793638b7..7e38cd0c3 100644 --- a/Doc/Zsh/redirect.yo +++ b/Doc/Zsh/redirect.yo @@ -26,6 +26,7 @@ separate filename in turn. startitem() item(tt(<) var(word))( Open file var(word) for reading as standard input. +It is an error to open a file in this fashion if it does not exist. ) item(tt(<>) var(word))( Open file var(word) for reading and writing as standard input. @@ -234,6 +235,9 @@ example(date >foo | cat) writes the date to the file `tt(foo)', and also pipes it to cat. +Note that the shell opens all the files to be used in the multio process +immediately, not at the point they are about to be written. + Note also that redirections are always expanded in order. This happens regardless of the setting of the tt(MULTIOS) option, but with the option in effect there are additional consequences. For example, @@ -268,9 +272,13 @@ example(echo exit 0 >> *.sh) If the user tries to open a file descriptor for reading more than once, the shell opens the file descriptor as a pipe to a process that copies -all the specified inputs to its output in the order -specified, similar to bf(cat), -provided the tt(MULTIOS) option is set. Thus +all the specified inputs to its output in the order specified, provided +the tt(MULTIOS) option is set. It should be noted that each file is +opened immediately, not at the point where it is about to be read: +this behaviour differs from tt(cat), so if strictly standard behaviour +is needed, tt(cat) should be used instead. + +Thus example(sort <foo <fubar) diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 6ae4863c6..fe4e5bd04 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -47,11 +47,11 @@ by default be entered in emacs mode by holding the alt key and typing a number, or pressing escape before each digit, and in vi command mode by typing the number before entering a command. Generally the numeric argument causes the next command entered to be repeated the specified -number of times, unless otherwise noted below. See also +number of times, unless otherwise noted below; this is implemented +by the tt(digit-argument) widget. See also ifzman(the em(Arguments) subsection of the em(Widgets) section )\ ifnzman(noderef(Arguments) )\ -for some other ways the numeric argument can be modified. The default -bindings mentioned here use the tt(digit-argument) widget. +for some other ways the numeric argument can be modified. startmenu() menu(Keymaps) @@ -2703,8 +2703,9 @@ this to appear with other types of highlighting; it is used to override a default. ) item(tt(fg=)var(colour))( -The foreground colour should be set to var(colour), a decimal integer -or the name of one of the eight most widely-supported colours. +The foreground colour should be set to var(colour), a decimal integer, +the name of one of the eight most widely-supported colours or as a +`tt(#)' followed by an RGB triplet in hexadecimal format. Not all terminals support this and, of those that do, not all provide facilities to test the support, hence the user should decide based on the @@ -2721,6 +2722,15 @@ Co)'; if this succeeds, it indicates a limit on the number of colours which will be enforced by the line editor. The number of colours is in any case limited to 256 (i.e. the range 0 to 255). +Some modern terminal emulators have support for 24-bit true colour (16 +million colours). In this case, the hex triplet format can be used. This +consists of either a three or six digit hexadecimal number describing +the red, green and blue components of the colour. Hex triplets can also +be used with 88 and 256 colour terminals via the tt(zsh/nearcolor) +module (see ifzman(zmanref(zshmodules))\ +ifnzman(noderef(The zsh/nearcolor Module))\ +). + Colour is also known as color. ) item(tt(bg=)var(colour))( |