From bf4be466765b6f490b15981ecb308664c817535b Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Tue, 25 May 2004 16:51:17 +0000 Subject: c.f users/7474: reorder option descriptions in subheadings. --- Doc/Zsh/options.yo | 1630 +++++++++++++++++++++++++++------------------------- 1 file changed, 838 insertions(+), 792 deletions(-) (limited to 'Doc') diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo index d67d2b16c..2ef11bf3e 100644 --- a/Doc/Zsh/options.yo +++ b/Doc/Zsh/options.yo @@ -52,17 +52,79 @@ appear in the list prefixed with `tt(no)'. Hence (unless tt(KSH_OPTION_PRINT) is set), `tt(setopt)' shows all options whose settings are changed from the default. +subsect(Changing Directories) startitem() -pindex(ALIASES) -cindex(aliases, expansion) -item(tt(ALIASES) )( -Expand aliases. +pindex(AUTO_CD) +cindex(cd, automatic) +item(tt(AUTO_CD) (tt(-J)))( +If a command is issued that can't be executed as a normal command, +and the command is the name of a directory, perform the tt(cd) +command to that directory. ) -pindex(ALL_EXPORT) -cindex(export, automatic) -item(tt(ALL_EXPORT) (tt(-a), ksh: tt(-a)))( -All parameters subsequently defined are automatically exported. +pindex(AUTO_PUSHD) +cindex(cd, behaving like pushd) +cindex(pushd, making cd behave like) +item(tt(AUTO_PUSHD) (tt(-N)))( +Make tt(cd) push the old directory onto the directory stack. +) +pindex(CDABLE_VARS) +cindex(cd, to parameter) +item(tt(CDABLE_VARS) (tt(-T)))( +If the argument to a tt(cd) command (or an implied tt(cd) with the +tt(AUTO_CD) option set) is not a directory, and does not begin with a +slash, try to expand the expression as if it were preceded by a `tt(~)' (see +noderef(Filename Expansion)). +) +pindex(CHASE_DOTS) +cindex(cd, with .. in argument) +item(tt(CHASE_DOTS))( +When changing to a directory containing a path segment `tt(..)' which would +otherwise be treated as canceling the previous segment in the path (in +other words, `tt(foo/..)' would be removed from the path, or if `tt(..)' is +the first part of the path, the last part of tt($PWD) would be deleted), +instead resolve the path to the physical directory. This option is +overridden by tt(CHASE_LINKS). + +For example, suppose tt(/foo/bar) is a link to the directory tt(/alt/rod). +Without this option set, `tt(cd /foo/bar/..)' changes to tt(/foo); with it +set, it changes to tt(/alt). The same applies if the current directory +is tt(/foo/bar) and `tt(cd ..)' is used. Note that all other symbolic +links in the path will also be resolved. +) +pindex(CHASE_LINKS) +cindex(links, symbolic) +cindex(symbolic links) +item(tt(CHASE_LINKS) (tt(-w)))( +Resolve symbolic links to their true values when changing directory. +This also has the effect of tt(CHASE_DOTS), i.e. a `tt(..)' path segment +will be treated as referring to the physical parent, even if the preceding +path segment is a symbolic link. +) +pindex(PUSHD_IGNORE_DUPS) +cindex(directory stack, ignoring duplicates) +item(tt(PUSHD_IGNORE_DUPS))( +Don't push multiple copies of the same directory onto the directory stack. +) +pindex(PUSHD_MINUS) +cindex(directory stack, controlling syntax) +item(tt(PUSHD_MINUS))( +Exchanges the meanings of `tt(PLUS())' and `tt(-)' +when used with a number to specify a directory in the stack. +) +pindex(PUSHD_SILENT) +cindex(directory stack, silencing) +item(tt(PUSHD_SILENT) (tt(-E)))( +Do not print the directory stack after tt(pushd) or tt(popd). +) +pindex(PUSHD_TO_HOME) +cindex(pushd, to home) +item(tt(PUSHD_TO_HOME) (tt(-D)))( +Have tt(pushd) with no arguments act like `tt(pushd $HOME)'. ) +enditem() + +subsect(Completion) +startitem() pindex(ALWAYS_LAST_PROMPT) item(tt(ALWAYS_LAST_PROMPT) )( If unset, key functions that list completions try to return to the last @@ -76,29 +138,6 @@ full completion is inserted, the cursor is moved to the end of the word. That is, the cursor is moved to the end of the word if either a single match is inserted or menu completion is performed. ) -pindex(APPEND_HISTORY) -cindex(history, appending to a file) -item(tt(APPEND_HISTORY) )( -If this is set, zsh sessions will append their history list to -the history file, rather than overwrite it. Thus, multiple parallel -zsh sessions will all have their history lists added to the -history file, in the order they are killed. -) -pindex(AUTO_CD) -cindex(cd, automatic) -item(tt(AUTO_CD) (tt(-J)))( -If a command is issued that can't be executed as a normal command, -and the command is the name of a directory, perform the tt(cd) -command to that directory. -) -pindex(AUTO_CONTINUE) -cindex(jobs, continuing automatically) -cindex(continuing jobs automatically) -item(tt(AUTO_CONTINUE))( -With this option set, stopped jobs that are removed from the job table -with the tt(disown) builtin command are automatically sent a tt(CONT) -signal to make them running. -) pindex(AUTO_LIST) cindex(completion, listing choices) item(tt(AUTO_LIST) (tt(-9)) )( @@ -137,12 +176,6 @@ item(tt(AUTO_PARAM_SLASH) )( If a parameter is completed whose content is the name of a directory, then add a trailing slash instead of a space. ) -pindex(AUTO_PUSHD) -cindex(cd, behaving like pushd) -cindex(pushd, making cd behave like) -item(tt(AUTO_PUSHD) (tt(-N)))( -Make tt(cd) push the old directory onto the directory stack. -) pindex(AUTO_REMOVE_SLASH) cindex(slash, removing trailing) item(tt(AUTO_REMOVE_SLASH) )( @@ -150,13 +183,104 @@ When the last character resulting from a completion is a slash and the next character typed is a word delimiter, a slash, or a character that ends a command (such as a semicolon or an ampersand), remove the slash. ) -pindex(AUTO_RESUME) -cindex(jobs, resuming automatically) -cindex(resuming jobs automatically) -item(tt(AUTO_RESUME) (tt(-W)))( -Treat single word simple commands without redirection -as candidates for resumption of an existing job. +pindex(BASH_AUTO_LIST) +cindex(completion, listing choices, bash style) +item(tt(BASH_AUTO_LIST))( +On an ambiguous completion, automatically list choices when the +completion function is called twice in succession. This takes +precedence over tt(AUTO_LIST). The setting of tt(LIST_AMBIGUOUS) is +respected. If tt(AUTO_MENU) is set, the menu behaviour will then start +with the third press. Note that this will not work with +tt(MENU_COMPLETE), since repeated completion calls immediately cycle +through the list in that case. +) +pindex(COMPLETE_ALIASES) +cindex(aliases, completion of) +item(tt(COMPLETE_ALIASES))( +Prevents aliases on the command line from being internally substituted +before completion is attempted. The effect is to make the alias a +distinct command for completion purposes. ) +pindex(COMPLETE_IN_WORD) +item(tt(COMPLETE_IN_WORD))( +If unset, the cursor is set to the end of the word if completion is +started. Otherwise it stays there and completion is done from both ends. +) +pindex(GLOB_COMPLETE) +item(tt(GLOB_COMPLETE))( +When the current word has a glob pattern, do not insert all the words +resulting from the expansion but generate matches as for completion and +cycle through them like tt(MENU_COMPLETE). The matches are generated as if +a `tt(*)' was added to the end of the word, or inserted at the cursor when +tt(COMPLETE_IN_WORD) is set. This actually uses pattern matching, not +globbing, so it works not only for files but for any completion, such as +options, user names, etc. +) +pindex(HASH_LIST_ALL) +item(tt(HASH_LIST_ALL) )( +Whenever a command completion is attempted, make sure the entire +command path is hashed first. This makes the first completion slower. +) +pindex(LIST_AMBIGUOUS) +cindex(ambiguous completion) +cindex(completion, ambiguous) +item(tt(LIST_AMBIGUOUS) )( +This option works when tt(AUTO_LIST) or tt(BASH_AUTO_LIST) is also +set. If there is an unambiguous prefix to insert on the command line, +that is done without a completion list being displayed; in other +words, auto-listing behaviour only takes place when nothing would be +inserted. In the case of tt(BASH_AUTO_LIST), this means that the list +will be delayed to the third call of the function. +) +pindex(LIST_BEEP) +cindex(beep, ambiguous completion) +cindex(completion, beep on ambiguous) +item(tt(LIST_BEEP) )( +Beep on an ambiguous completion. More accurately, this forces the +completion widgets to return status 1 on an ambiguous completion, which +causes the shell to beep if the option tt(BEEP) is also set; this may +be modified if completion is called from a user-defined widget. +) +pindex(LIST_PACKED) +cindex(completion, listing) +item(tt(LIST_PACKED))( +Try to make the completion list smaller (occupying less lines) by +printing the matches in columns with different widths. +) +pindex(LIST_ROWS_FIRST) +cindex(completion, listing order) +item(tt(LIST_ROWS_FIRST))( +Lay out the matches in completion lists sorted horizontally, that is, +the second match is to the right of the first one, not under it as +usual. +) +pindex(LIST_TYPES) +cindex(marking file types) +cindex(files, marking type of) +item(tt(LIST_TYPES) (tt(-X)) )( +When listing files that are possible completions, show the +type of each file with a trailing identifying mark. +) +pindex(MENU_COMPLETE) +cindex(completion, menu) +item(tt(MENU_COMPLETE) (tt(-Y)))( +On an ambiguous completion, instead of listing possibilities or beeping, +insert the first match immediately. Then when completion is requested +again, remove the first match and insert the second match, etc. +When there are no more matches, go back to the first one again. +tt(reverse-menu-complete) may be used to loop through the list +in the other direction. This option overrides tt(AUTO_MENU). +) +pindex(REC_EXACT) +cindex(completion, exact matches) +item(tt(REC_EXACT) (tt(-S)))( +In completion, recognize exact matches even +if they are ambiguous. +) +enditem() + +subsect(Expansion and Globbing) +startitem() pindex(BAD_PATTERN) cindex(globbing, bad pattern) cindex(filename generation, bad pattern) @@ -164,13 +288,6 @@ item(tt(BAD_PATTERN) (tt(PLUS()2)) )( If a pattern for filename generation is badly formed, print an error message. (If this option is unset, the pattern will be left unchanged.) ) -pindex(BANG_HIST) -cindex(history, enable substitution) -cindex(enable history substitution) -item(tt(BANG_HIST) (tt(PLUS()K)) )( -Perform textual history expansion, bf(csh)-style, -treating the character `tt(!)' specially. -) pindex(BARE_GLOB_QUAL) cindex(globbing qualifiers, enable) cindex(enable globbing qualifiers) @@ -179,31 +296,6 @@ In a glob pattern, treat a trailing set of parentheses as a qualifier list, if it contains no `tt(|)', `tt(LPAR())' or (if special) `tt(~)' characters. See noderef(Filename Generation). ) -pindex(BASH_AUTO_LIST) -cindex(completion, listing choices, bash style) -item(tt(BASH_AUTO_LIST))( -On an ambiguous completion, automatically list choices when the -completion function is called twice in succession. This takes -precedence over tt(AUTO_LIST). The setting of tt(LIST_AMBIGUOUS) is -respected. If tt(AUTO_MENU) is set, the menu behaviour will then start -with the third press. Note that this will not work with -tt(MENU_COMPLETE), since repeated completion calls immediately cycle -through the list in that case. -) -pindex(BEEP) -cindex(beep, enabling) -cindex(enabling the beep) -item(tt(BEEP) (tt(PLUS()B)) )( -Beep on error in ZLE. -) -pindex(BG_NICE) -cindex(jobs, background priority) -cindex(background jobs, priority of) -cindex(priority of background jobs) -item(tt(BG_NICE) (tt(-6)) )( -Run all background jobs at a lower priority. This option -is set by default. -) pindex(BRACE_CCL) cindex(brace expansion, extending) cindex(expansion, brace, extending) @@ -212,13 +304,6 @@ Expand expressions in braces which would not otherwise undergo brace expansion to a lexically ordered list of all the characters. See noderef(Brace Expansion). ) -pindex(BSD_ECHO) -cindex(echo, BSD compatible) -item(tt(BSD_ECHO) )( -Make the tt(echo) builtin compatible with the BSD manref(echo)(1) command. -This disables backslashed escape sequences in echo strings unless the -tt(-e) option is specified. -) pindex(CASE_GLOB) cindex(case-insensitive globbing, option) item(tt(CASE_GLOB) )( @@ -229,137 +314,6 @@ will cause case-insensitive matching. For example, tt(cvs(/)) can match the directory tt(CVS) owing to the presence of the globbing flag (unless the option tt(BARE_GLOB_QUAL) is unset). ) -pindex(C_BASES) -cindex(bases, output in C format) -cindex(hexadecimal, output in C format) -cindex(octal, output in C format) -item(tt(C_BASES))( -Output hexadecimal numbers in the standard C format, for example `tt(0xFF)' -instead of the usual `tt(16#FF)'. If the option tt(OCTAL_ZEROES) is also -set (it is not by default), octal numbers will be treated similarly and -hence appear as `tt(077)' instead of `tt(8#77)'. This option has no effect -on the choice of the output base, nor on the output of bases other than -hexadecimal and octal. Note that these formats will be understood on input -irrespective of the setting of tt(C_BASES). -) -pindex(CDABLE_VARS) -cindex(cd, to parameter) -item(tt(CDABLE_VARS) (tt(-T)))( -If the argument to a tt(cd) command (or an implied tt(cd) with the -tt(AUTO_CD) option set) is not a directory, and does not begin with a -slash, try to expand the expression as if it were preceded by a `tt(~)' (see -noderef(Filename Expansion)). -) -pindex(CHASE_DOTS) -cindex(cd, with .. in argument) -item(tt(CHASE_DOTS))( -When changing to a directory containing a path segment `tt(..)' which would -otherwise be treated as canceling the previous segment in the path (in -other words, `tt(foo/..)' would be removed from the path, or if `tt(..)' is -the first part of the path, the last part of tt($PWD) would be deleted), -instead resolve the path to the physical directory. This option is -overridden by tt(CHASE_LINKS). - -For example, suppose tt(/foo/bar) is a link to the directory tt(/alt/rod). -Without this option set, `tt(cd /foo/bar/..)' changes to tt(/foo); with it -set, it changes to tt(/alt). The same applies if the current directory -is tt(/foo/bar) and `tt(cd ..)' is used. Note that all other symbolic -links in the path will also be resolved. -) -pindex(CHASE_LINKS) -cindex(links, symbolic) -cindex(symbolic links) -item(tt(CHASE_LINKS) (tt(-w)))( -Resolve symbolic links to their true values when changing directory. -This also has the effect of tt(CHASE_DOTS), i.e. a `tt(..)' path segment -will be treated as referring to the physical parent, even if the preceding -path segment is a symbolic link. -) -pindex(CHECK_JOBS) -cindex(exiting, checking jobs when) -cindex(logging out, checking jobs when) -item(tt(CHECK_JOBS) )( -Report the status of background and suspended jobs before exiting a shell -with job control; a second attempt to exit the shell will succeed. -tt(NO_CHECK_JOBS) is best used only in combination with tt(NO_HUP), else -such jobs will be killed automatically. - -The check is omitted if the commands run from the previous command line -included a `tt(jobs)' command, since it is assumed the user is aware that -there are background or suspended jobs. A `tt(jobs)' command run from the -tt(precmd) function is not counted for this purpose. -) -pindex(CLOBBER) -cindex(clobbering, of files) -cindex(file clobbering, allowing) -item(tt(CLOBBER) (tt(PLUS()C), ksh: tt(PLUS()C)) )( -Allows `tt(>)' redirection to truncate existing files, -and `tt(>>)' to create files. -Otherwise `tt(>!)' or `tt(>|)' must be used to truncate a file, -and `tt(>>!)' or `tt(>>|)' to create a file. -) -pindex(COMPLETE_ALIASES) -cindex(aliases, completion of) -item(tt(COMPLETE_ALIASES))( -Prevents aliases on the command line from being internally substituted -before completion is attempted. The effect is to make the alias a -distinct command for completion purposes. -) -pindex(COMPLETE_IN_WORD) -item(tt(COMPLETE_IN_WORD))( -If unset, the cursor is set to the end of the word if completion is -started. Otherwise it stays there and completion is done from both ends. -) -pindex(CORRECT) -cindex(correction, spelling) -cindex(spelling correction) -item(tt(CORRECT) (tt(-0)))( -Try to correct the spelling of commands. -Note that, when the tt(HASH_LIST_ALL) option is not set or when some -directories in the path are not readable, this may falsely report spelling -errors the first time some commands are used. -) -pindex(CORRECT_ALL) -item(tt(CORRECT_ALL) (tt(-O)))( -Try to correct the spelling of all arguments in a line. -) -pindex(CSH_JUNKIE_HISTORY) -cindex(csh, history style) -cindex(history style, csh) -item(tt(CSH_JUNKIE_HISTORY) )( -A history reference without an event specifier will always refer to the -previous command. Without this option, such a history reference refers -to the same event as the previous history reference, defaulting to the -previous command. -) -pindex(CSH_JUNKIE_LOOPS) -cindex(csh, loop style) -cindex(loop style, csh) -item(tt(CSH_JUNKIE_LOOPS) )( -Allow loop bodies to take the form `var(list); tt(end)' instead of -`tt(do) var(list); tt(done)'. -) -pindex(CSH_JUNKIE_QUOTES) -cindex(csh, quoting style) -cindex(quoting style, csh) -item(tt(CSH_JUNKIE_QUOTES) )( -Changes the rules for single- and double-quoted text to match that of -bf(csh). These require that embedded newlines be preceded by a backslash; -unescaped newlines will cause an error message. -In double-quoted strings, it is made impossible to escape `tt($)', `tt(`)' -or `tt(")' (and `tt(\)' itself no longer needs escaping). -Command substitutions are only expanded once, and cannot be nested. -) -pindex(CSH_NULLCMD) -vindex(NULLCMD, ignoring) -vindex(READNULLCMD, ignoring) -cindex(redirections with no command, csh) -cindex(csh, redirections with no command) -item(tt(CSH_NULLCMD) )( -Do not use the values of tt(NULLCMD) and tt(READNULLCMD) -when running redirections with no command. This make -such redirections fail (see noderef(Redirection)). -) pindex(CSH_NULL_GLOB) cindex(csh, null globbing style) cindex(null globbing style, csh) @@ -371,51 +325,12 @@ do not report an error unless all the patterns in a command have no matches. Overrides tt(NOMATCH). ) -pindex(DVORAK) -item(tt(DVORAK))( -Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis -for examining spelling mistakes for the tt(CORRECT) and tt(CORRECT_ALL) -options and the tt(spell-word) editor command. -) -pindex(EMACS) -item(tt(EMACS))( -If ZLE is loaded, turning on this option has the equivalent effect -of `tt(bindkey -e)'. In addition, the VI option is unset. -Turning it off has no effect. The option setting is -not guaranteed to reflect the current keymap. This option is -provided for compatibility; tt(bindkey) is the recommended interface. -) pindex(EQUALS) cindex(filename expansion, =) item(tt(EQUALS) )( Perform tt(=) filename expansion. (See noderef(Filename Expansion).) ) -pindex(ERR_EXIT) -cindex(exit status, trapping) -item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( -If a command has a non-zero exit status, execute the tt(ZERR) -trap, if set, and exit. This is disabled while running initialization -scripts. -) -pindex(ERR_RETURN) -cindex(function return, on error) -cidnex(return from function, on error) -item(tt(ERR_RETURN))( -If a command has a non-zero exit status, return immediately from the -enclosing function. The logic is identical to that for tt(ERR_EXIT), -except that an implicit tt(return) statement is executed instead of an -tt(exit). This will trigger an exit at the outermost level of a -non-interactive script. -) -pindex(EXEC) -cindex(command execution, enabling) -item(tt(EXEC) (tt(PLUS()n), ksh: tt(PLUS()n)) )( -Do execute commands. Without this option, commands are -read and checked for syntax errors, but not executed. -This option cannot be turned off in an interactive shell, -except when `tt(-n)' is supplied to the shell at startup. -) pindex(EXTENDED_GLOB) cindex(globbing, extended) item(tt(EXTENDED_GLOB))( @@ -423,28 +338,6 @@ Treat the `tt(#)', `tt(~)' and `tt(^)' characters as part of patterns for filename generation, etc. (An initial unquoted `tt(~)' always produces named directory expansion.) ) -pindex(EXTENDED_HISTORY) -cindex(history, timestamping) -item(tt(EXTENDED_HISTORY) )( -Save each command's beginning timestamp (in seconds since the epoch) -and the duration (in seconds) to the history file. The format of -this prefixed data is: - -`tt(:)var()tt(:)var()tt(:)var()'. -) -pindex(FLOW_CONTROL) -cindex(flow control) -item(tt(FLOW_CONTROL) )( -If this option is unset, -output flow control via start/stop characters (usually assigned to -^S/^Q) is disabled in the shell's editor. -) -pindex(FUNCTION_ARGZERO) -cindex($0, setting) -item(tt(FUNCTION_ARGZERO) )( -When executing a shell function or sourcing a script, set tt($0) -temporarily to the name of the function/script. -) pindex(GLOB) cindex(globbing, enabling) cindex(enabling globbing) @@ -452,33 +345,6 @@ item(tt(GLOB) (tt(PLUS()F), ksh: tt(PLUS()f)) )( Perform filename generation (globbing). (See noderef(Filename Generation).) ) -pindex(GLOBAL_EXPORT) -cindex(environment, and local parameters) -item(tt(GLOBAL_EXPORT) (tt()))( -If this option is set, passing the tt(-x) flag to the builtins tt(declare), -tt(float), tt(integer), tt(readonly) and tt(typeset) (but not tt(local)) -will also set the tt(-g) flag; hence parameters exported to -the environment will not be made local to the enclosing function, unless -they were already or the flag tt(+g) is given explicitly. If the option is -unset, exported parameters will be made local in just the same way as any -other parameter. - -This option is set by default for backward compatibility; it is not -recommended that its behaviour be relied upon. Note that the builtin -tt(export) always sets both the tt(-x) and tt(-g) flags, and hence its -effect extends beyond the scope of the enclosing function; this is the -most portable way to achieve this behaviour. -) -cindex(exporting, and local parameters) -pindex(GLOBAL_RCS) -cindex(startup files, global, inhibiting) -cindex(files, global startup, inhibiting) -item(tt(GLOBAL_RCS) (tt(-d)) )( -If this option is unset, the startup files tt(/etc/zprofile), -tt(/etc/zshrc), tt(/etc/zlogin) and tt(/etc/zlogout) will not be run. It -can be disabled and re-enabled at any time, including inside local startup -files (tt(.zshrc), etc.). -) pindex(GLOB_ASSIGN) item(tt(GLOB_ASSIGN) )( If this option is set, filename generation (globbing) is @@ -492,16 +358,6 @@ of array assignments of the form `var(name)tt(=LPAR())var(value)tt(RPAR())' with this option set, it is not possible to predict whether the result will be an array or a scalar. ) -pindex(GLOB_COMPLETE) -item(tt(GLOB_COMPLETE))( -When the current word has a glob pattern, do not insert all the words -resulting from the expansion but generate matches as for completion and -cycle through them like tt(MENU_COMPLETE). The matches are generated as if -a `tt(*)' was added to the end of the word, or inserted at the cursor when -tt(COMPLETE_IN_WORD) is set. This actually uses pattern matching, not -globbing, so it works not only for files but for any completion, such as -options, user names, etc. -) pindex(GLOB_DOTS) cindex(globbing, of . files) item(tt(GLOB_DOTS) (tt(-4)))( @@ -515,34 +371,121 @@ characters resulting from command substitution as being eligible for filename generation. Braces (and commas in between) do not become eligible for expansion. ) -pindex(HASH_CMDS) -cindex(hashing, of commands) -cindex(command hashing) -item(tt(HASH_CMDS) )( -Note the location of each command the first time it is executed. -Subsequent invocations of the same command will use the -saved location, avoiding a path search. -If this option is unset, no path hashing is done at all. -However, when tt(CORRECT) is set, commands whose names do not appear in -the functions or aliases hash tables are hashed in order to avoid -reporting them as spelling errors. -) -pindex(HASH_DIRS) -cindex(hashing, of directories) -cindex(directories, hashing) -item(tt(HASH_DIRS) )( -Whenever a command name is hashed, hash the directory containing it, -as well as all directories that occur earlier in the path. -Has no effect if neither tt(HASH_CMDS) nor tt(CORRECT) is set. +pindex(IGNORE_BRACES) +cindex(disabling brace expansion) +cindex(brace expansion, disabling) +cindex(expansion, brace, disabling) +item(tt(IGNORE_BRACES) (tt(-I)) )( +Do not perform brace expansion. ) -pindex(HASH_LIST_ALL) -item(tt(HASH_LIST_ALL) )( -Whenever a command completion is attempted, make sure the entire -command path is hashed first. This makes the first completion slower. +pindex(KSH_GLOB) +item(tt(KSH_GLOB) )( +In pattern matching, the interpretation of parentheses is affected by +a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'. +See noderef(Filename Generation). ) -pindex(HIST_ALLOW_CLOBBER) -item(tt(HIST_ALLOW_CLOBBER))( -Add `tt(|)' to output redirections in the history. This allows history +pindex(MAGIC_EQUAL_SUBST) +item(tt(MAGIC_EQUAL_SUBST))( +All unquoted arguments of the form `var(anything)tt(=)var(expression)' +appearing after the command name have filename expansion (that is, +where var(expression) has a leading `tt(~)' or `tt(=)') performed on +var(expression) as if it were a parameter assignment. The argument is +not otherwise treated specially; it is passed to the command as a single +argument, and not used as an actual parameter assignment. For example, in +tt(echo foo=~/bar:~/rod), both occurrences of tt(~) would be replaced. +Note that this happens anyway with tt(typeset) and similar statements. + +This option respects the setting of the tt(KSH_TYPESET) option. In other +words, if both options are in effect, arguments looking like +assignments will not undergo wordsplitting. +) +pindex(MARK_DIRS) +cindex(directories, marking) +cindex(marking directories) +item(tt(MARK_DIRS) (tt(-8), ksh: tt(-X)))( +Append a trailing `tt(/)' to all directory +names resulting from filename generation (globbing). +) +pindex(NOMATCH) +cindex(globbing, no matches) +item(tt(NOMATCH) (tt(PLUS()3)) )( +If a pattern for filename generation has no matches, +print an error, instead of +leaving it unchanged in the argument list. +This also applies to file expansion +of an initial `tt(~)' or `tt(=)'. +) +pindex(NULL_GLOB) +cindex(globbing, no matches) +item(tt(NULL_GLOB) (tt(-G)))( +If a pattern for filename generation has no matches, +delete the pattern from the argument list instead +of reporting an error. Overrides tt(NOMATCH). +) +pindex(NUMERIC_GLOB_SORT) +cindex(globbing, sorting numerically) +item(tt(NUMERIC_GLOB_SORT))( +If numeric filenames are matched by a filename generation pattern, +sort the filenames numerically rather than lexicographically. +) +pindex(RC_EXPAND_PARAM) +cindex(rc, parameter expansion style) +cindex(parameter expansion style, rc) +item(tt(RC_EXPAND_PARAM) (tt(-P)))( +Array expansions of the form +`var(foo)tt(${)var(xx)tt(})var(bar)', where the parameter +var(xx) is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with +`var(fooabar foobbar foocbar)' instead of the default +`var(fooa b cbar)'. +) +pindex(SH_GLOB) +cindex(sh, globbing style) +cindex(globbing style, sh) +item(tt(SH_GLOB) )( +Disables the special meaning of `tt(LPAR())', `tt(|)', `tt(RPAR())' +and 'tt(<)' for globbing the result of parameter and command substitutions, +and in some other places where +the shell accepts patterns. This option is set by default if zsh is +invoked as tt(sh) or tt(ksh). +) +pindex(UNSET) +cindex(parameters, substituting unset) +cindex(unset parameters, substituting) +item(tt(UNSET) (tt(PLUS()u), ksh: tt(PLUS()u)) )( +Treat unset parameters as if they were empty when substituting. +Otherwise they are treated as an error. +) +enditem() + +subsect(History) +startitem() +pindex(APPEND_HISTORY) +cindex(history, appending to a file) +item(tt(APPEND_HISTORY) )( +If this is set, zsh sessions will append their history list to +the history file, rather than overwrite it. Thus, multiple parallel +zsh sessions will all have their history lists added to the +history file, in the order they are killed. +) +pindex(BANG_HIST) +cindex(history, enable substitution) +cindex(enable history substitution) +item(tt(BANG_HIST) (tt(PLUS()K)) )( +Perform textual history expansion, bf(csh)-style, +treating the character `tt(!)' specially. +) +pindex(EXTENDED_HISTORY) +cindex(history, timestamping) +item(tt(EXTENDED_HISTORY) )( +Save each command's beginning timestamp (in seconds since the epoch) +and the duration (in seconds) to the history file. The format of +this prefixed data is: + +`tt(:)var()tt(:)var()tt(:)var()'. +) +pindex(HIST_ALLOW_CLOBBER) +item(tt(HIST_ALLOW_CLOBBER))( +Add `tt(|)' to output redirections in the history. This allows history references to clobber files even when tt(CLOBBER) is unset. ) pindex(HIST_BEEP) @@ -626,18 +569,129 @@ Whenever the user enters a line with history expansion, don't execute the line directly; instead, perform history expansion and reload the line into the editing buffer. ) -pindex(HUP) -cindex(jobs, HUP) -item(tt(HUP) )( -Send the tt(HUP) signal to running jobs when the -shell exits. +pindex(INC_APPEND_HISTORY) +cindex(history, incremental appending to a file) +item(tt(INC_APPEND_HISTORY))( +This options works like tt(APPEND_HISTORY) except that new history lines +are added to the tt($HISTFILE) incrementally (as soon as they are +entered), rather than waiting until the shell is killed. +The file is periodically trimmed to the number of lines specified by +tt($SAVEHIST), but can exceed this value between trimmings. ) -pindex(IGNORE_BRACES) -cindex(disabling brace expansion) -cindex(brace expansion, disabling) -cindex(expansion, brace, disabling) -item(tt(IGNORE_BRACES) (tt(-I)) )( -Do not perform brace expansion. +pindex(SHARE_HISTORY) +cindex(share history) +cindex(history, sharing) +item(tt(SHARE_HISTORY) )( + +This option both imports new commands from the history file, and also +causes your typed commands to be appended to the history file (the +latter is like specifying tt(INC_APPEND_HISTORY)). +The history lines are also output with timestamps ala +tt(EXTENDED_HISTORY) (which makes it easier to find the spot where +we left off reading the file after it gets re-written). + +By default, history movement commands visit the imported lines as +well as the local lines, but you can toggle this on and off with the +set-local-history zle binding. It is also possible to create a zle +widget that will make some commands ignore imported commands, and +some include them. + +If you find that you want more control over when commands +get imported, you may wish to turn tt(SHARE_HISTORY) off, +tt(INC_APPEND_HISTORY) on, and then manually import +commands whenever you need them using `tt(fc -RI)'. +) +enditem() + +subsect(Initialisation) +startitem() +pindex(ALL_EXPORT) +cindex(export, automatic) +item(tt(ALL_EXPORT) (tt(-a), ksh: tt(-a)))( +All parameters subsequently defined are automatically exported. +) +pindex(GLOBAL_EXPORT) +cindex(environment, and local parameters) +item(tt(GLOBAL_EXPORT) (tt()))( +If this option is set, passing the tt(-x) flag to the builtins tt(declare), +tt(float), tt(integer), tt(readonly) and tt(typeset) (but not tt(local)) +will also set the tt(-g) flag; hence parameters exported to +the environment will not be made local to the enclosing function, unless +they were already or the flag tt(+g) is given explicitly. If the option is +unset, exported parameters will be made local in just the same way as any +other parameter. + +This option is set by default for backward compatibility; it is not +recommended that its behaviour be relied upon. Note that the builtin +tt(export) always sets both the tt(-x) and tt(-g) flags, and hence its +effect extends beyond the scope of the enclosing function; this is the +most portable way to achieve this behaviour. +) +cindex(exporting, and local parameters) +pindex(GLOBAL_RCS) +cindex(startup files, global, inhibiting) +cindex(files, global startup, inhibiting) +item(tt(GLOBAL_RCS) (tt(-d)) )( +If this option is unset, the startup files tt(/etc/zprofile), +tt(/etc/zshrc), tt(/etc/zlogin) and tt(/etc/zlogout) will not be run. It +can be disabled and re-enabled at any time, including inside local startup +files (tt(.zshrc), etc.). +) +pindex(RCS) +cindex(startup files, sourcing) +item(tt(RCS) (tt(PLUS()f)) )( +After tt(/etc/zshenv) is sourced on startup, source the +tt(.zshenv), tt(/etc/zprofile), tt(.zprofile), +tt(/etc/zshrc), tt(.zshrc), tt(/etc/zlogin), tt(.zlogin), and tt(.zlogout) +files, as described in noderef(Files). +If this option is unset, the tt(/etc/zshenv) file is still sourced, but any +of the others will not be; it can be set at any time to prevent the +remaining startup files after the currently executing one from +being sourced. +) +enditem() + +subsect(Input/Output) +startitem() +pindex(ALIASES) +cindex(aliases, expansion) +item(tt(ALIASES) )( +Expand aliases. +) +pindex(CLOBBER) +cindex(clobbering, of files) +cindex(file clobbering, allowing) +item(tt(CLOBBER) (tt(PLUS()C), ksh: tt(PLUS()C)) )( +Allows `tt(>)' redirection to truncate existing files, +and `tt(>>)' to create files. +Otherwise `tt(>!)' or `tt(>|)' must be used to truncate a file, +and `tt(>>!)' or `tt(>>|)' to create a file. +) +pindex(CORRECT) +cindex(correction, spelling) +cindex(spelling correction) +item(tt(CORRECT) (tt(-0)))( +Try to correct the spelling of commands. +Note that, when the tt(HASH_LIST_ALL) option is not set or when some +directories in the path are not readable, this may falsely report spelling +errors the first time some commands are used. +) +pindex(CORRECT_ALL) +item(tt(CORRECT_ALL) (tt(-O)))( +Try to correct the spelling of all arguments in a line. +) +pindex(DVORAK) +item(tt(DVORAK))( +Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis +for examining spelling mistakes for the tt(CORRECT) and tt(CORRECT_ALL) +options and the tt(spell-word) editor command. +) +pindex(FLOW_CONTROL) +cindex(flow control) +item(tt(FLOW_CONTROL) )( +If this option is unset, +output flow control via start/stop characters (usually assigned to +^S/^Q) is disabled in the shell's editor. ) pindex(IGNORE_EOF) cindex(EOF, ignoring) @@ -652,167 +706,30 @@ implemented by shell functions can be bound to EOF (normally Control-D) without printing the normal warning message. This works only for normal widgets, not for completion widgets. ) -pindex(INC_APPEND_HISTORY) -cindex(history, incremental appending to a file) -item(tt(INC_APPEND_HISTORY))( -This options works like tt(APPEND_HISTORY) except that new history lines -are added to the tt($HISTFILE) incrementally (as soon as they are -entered), rather than waiting until the shell is killed. -The file is periodically trimmed to the number of lines specified by -tt($SAVEHIST), but can exceed this value between trimmings. -) -pindex(INTERACTIVE) -item(tt(INTERACTIVE) (tt(-i), ksh: tt(-i)))( -This is an interactive shell. This option is set upon initialisation if -the standard input is a tty and commands are being read from standard input. -(See the discussion of tt(SHIN_STDIN).) -This heuristic may be overridden by specifying a state for this option -on the command line. -The value of this option cannot be changed anywhere other than the command line. -) pindex(INTERACTIVE_COMMENTS) cindex(comments, in interactive shells) item(tt(INTERACTIVE_COMMENTS) (tt(-k)) )( Allow comments even in interactive shells. ) -pindex(KSH_ARRAYS) -cindex(arrays, ksh style) -cindex(array style, ksh) -cindex(ksh, array style) -item(tt(KSH_ARRAYS) )( -Emulate bf(ksh) array handling as closely as possible. If this option -is set, array elements are numbered from zero, an array parameter -without subscript refers to the first element instead of the whole array, -and braces are required to delimit a subscript (`tt(${path[2]})' rather -than just `tt($path[2])'). -) -pindex(KSH_AUTOLOAD) -item(tt(KSH_AUTOLOAD) )( -Emulate bf(ksh) function autoloading. This means that when a function is -autoloaded, the corresponding file is merely executed, and must define -the function itself. (By default, the function is defined to the contents -of the file. However, the most common bf(ksh)-style case - of the file -containing only a simple definition of the function - is always handled -in the bf(ksh)-compatible manner.) -) -pindex(KSH_GLOB) -item(tt(KSH_GLOB) )( -In pattern matching, the interpretation of parentheses is affected by -a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'. -See noderef(Filename Generation). -) -pindex(KSH_OPTION_PRINT) -cindex(option printing, ksh style) -cindex(option printing style, ksh) -cindex(ksh, option printing style) -item(tt(KSH_OPTION_PRINT) )( -Alters the way options settings are printed: instead of separate lists of -set and unset options, all options are shown, marked `on' if -they are in the non-default state, `off' otherwise. -) -pindex(KSH_TYPESET) -cindex(argument splitting, in typeset etc.) -cindex(ksh, argument splitting in typeset) -item(tt(KSH_TYPESET) )( -Alters the way arguments to the tt(typeset) family of commands, including -tt(declare), tt(export), tt(float), tt(integer), tt(local) and -tt(readonly), are processed. Without this option, zsh will perform normal -word splitting after command and parameter expansion in arguments of an -assignment; with it, word splitting does not take place in those cases. -) -pindex(LIST_AMBIGUOUS) -cindex(ambiguous completion) -cindex(completion, ambiguous) -item(tt(LIST_AMBIGUOUS) )( -This option works when tt(AUTO_LIST) or tt(BASH_AUTO_LIST) is also -set. If there is an unambiguous prefix to insert on the command line, -that is done without a completion list being displayed; in other -words, auto-listing behaviour only takes place when nothing would be -inserted. In the case of tt(BASH_AUTO_LIST), this means that the list -will be delayed to the third call of the function. -) -pindex(LIST_BEEP) -cindex(beep, ambiguous completion) -cindex(completion, beep on ambiguous) -item(tt(LIST_BEEP) )( -Beep on an ambiguous completion. More accurately, this forces the -completion widgets to return status 1 on an ambiguous completion, which -causes the shell to beep if the option tt(BEEP) is also set; this may -be modified if completion is called from a user-defined widget. -) -pindex(LIST_PACKED) -cindex(completion, listing) -item(tt(LIST_PACKED))( -Try to make the completion list smaller (occupying less lines) by -printing the matches in columns with different widths. -) -pindex(LIST_ROWS_FIRST) -cindex(completion, listing order) -item(tt(LIST_ROWS_FIRST))( -Lay out the matches in completion lists sorted horizontally, that is, -the second match is to the right of the first one, not under it as -usual. -) -pindex(LIST_TYPES) -cindex(marking file types) -cindex(files, marking type of) -item(tt(LIST_TYPES) (tt(-X)) )( -When listing files that are possible completions, show the -type of each file with a trailing identifying mark. -) -pindex(LOCAL_OPTIONS) -item(tt(LOCAL_OPTIONS) )( -If this option is set at the point of return from a shell function, -all the options (including this one) which were in force upon entry to -the function are restored. Otherwise, only this option and the -tt(XTRACE) and tt(PRINT_EXIT_VALUE) options are restored. Hence -if this is explicitly unset by a shell function the other options in -force at the point of return will remain so. -A shell function can also guarantee itself a known shell configuration -with a formulation like `tt(emulate -L zsh)'; the tt(-L) activates -tt(LOCAL_OPTIONS). -) -pindex(LOCAL_TRAPS) -item(tt(LOCAL_TRAPS) )( -If this option is set when a signal trap is set inside a function, then the -previous status of the trap for that signal will be restored when the -function exits. Note that this option must be set em(prior) to altering the -trap behaviour in a function; unlike tt(LOCAL_OPTIONS), the value on exit -from the function is irrelevant. However, it does not need to be set -before any global trap for that to be correctly restored by a function. -For example, - -example(unsetopt localtraps -trap - INT -fn() { setopt localtraps; trap '' INT; sleep 3; }) - -will restore normally handling of tt(SIGINT) after the function exits. -) -pindex(LOGIN) -item(tt(LOGIN) (tt(-l), ksh: tt(-l)))( -This is a login shell. -If this option is not explicitly set, the shell is a login shell if -the first character of the tt(argv[0]) passed to the shell is a `tt(-)'. -) -pindex(LONG_LIST_JOBS) -cindex(jobs, list format) -item(tt(LONG_LIST_JOBS) (tt(-R)))( -List jobs in the long format by default. +pindex(HASH_CMDS) +cindex(hashing, of commands) +cindex(command hashing) +item(tt(HASH_CMDS) )( +Note the location of each command the first time it is executed. +Subsequent invocations of the same command will use the +saved location, avoiding a path search. +If this option is unset, no path hashing is done at all. +However, when tt(CORRECT) is set, commands whose names do not appear in +the functions or aliases hash tables are hashed in order to avoid +reporting them as spelling errors. ) -pindex(MAGIC_EQUAL_SUBST) -item(tt(MAGIC_EQUAL_SUBST))( -All unquoted arguments of the form `var(anything)tt(=)var(expression)' -appearing after the command name have filename expansion (that is, -where var(expression) has a leading `tt(~)' or `tt(=)') performed on -var(expression) as if it were a parameter assignment. The argument is -not otherwise treated specially; it is passed to the command as a single -argument, and not used as an actual parameter assignment. For example, in -tt(echo foo=~/bar:~/rod), both occurrences of tt(~) would be replaced. -Note that this happens anyway with tt(typeset) and similar statements. - -This option respects the setting of the tt(KSH_TYPESET) option. In other -words, if both options are in effect, arguments looking like -assignments will not undergo wordsplitting. +pindex(HASH_DIRS) +cindex(hashing, of directories) +cindex(directories, hashing) +item(tt(HASH_DIRS) )( +Whenever a command name is hashed, hash the directory containing it, +as well as all directories that occur earlier in the path. +Has no effect if neither tt(HASH_CMDS) nor tt(CORRECT) is set. ) pindex(MAIL_WARNING) cindex(mail, warning of reading) @@ -820,76 +737,6 @@ item(tt(MAIL_WARNING) (tt(-U)))( Print a warning message if a mail file has been accessed since the shell last checked. ) -pindex(MARK_DIRS) -cindex(directories, marking) -cindex(marking directories) -item(tt(MARK_DIRS) (tt(-8), ksh: tt(-X)))( -Append a trailing `tt(/)' to all directory -names resulting from filename generation (globbing). -) -pindex(MENU_COMPLETE) -cindex(completion, menu) -item(tt(MENU_COMPLETE) (tt(-Y)))( -On an ambiguous completion, instead of listing possibilities or beeping, -insert the first match immediately. Then when completion is requested -again, remove the first match and insert the second match, etc. -When there are no more matches, go back to the first one again. -tt(reverse-menu-complete) may be used to loop through the list -in the other direction. This option overrides tt(AUTO_MENU). -) -pindex(MONITOR) -cindex(job control, allowing) -item(tt(MONITOR) (tt(-m), ksh: tt(-m)))( -Allow job control. Set by default in interactive shells. -) -pindex(MULTIOS) -item(tt(MULTIOS) )( -Perform implicit bf(tee)s or bf(cat)s when multiple -redirections are attempted (see noderef(Redirection)). -) -pindex(NOMATCH) -cindex(globbing, no matches) -item(tt(NOMATCH) (tt(PLUS()3)) )( -If a pattern for filename generation has no matches, -print an error, instead of -leaving it unchanged in the argument list. -This also applies to file expansion -of an initial `tt(~)' or `tt(=)'. -) -pindex(NOTIFY) -cindex(background jobs, notification) -cindex(notification of background jobs) -item(tt(NOTIFY) (tt(-5), ksh: tt(-b)) )( -Report the status of background jobs immediately, rather than -waiting until just before printing a prompt. -) -pindex(NULL_GLOB) -cindex(globbing, no matches) -item(tt(NULL_GLOB) (tt(-G)))( -If a pattern for filename generation has no matches, -delete the pattern from the argument list instead -of reporting an error. Overrides tt(NOMATCH). -) -pindex(NUMERIC_GLOB_SORT) -cindex(globbing, sorting numerically) -item(tt(NUMERIC_GLOB_SORT))( -If numeric filenames are matched by a filename generation pattern, -sort the filenames numerically rather than lexicographically. -) -pindex(OCTAL_ZEROES) -cindex(octal, arithmetic expressions) -item(tt(OCTAL_ZEROES) )( -Interpret any integer constant beginning with a 0 as octal, per IEEE Std -1003.2-1992 (ISO 9945-2:1993). This is not enabled by default as it -causes problems with parsing of, for example, date and time strings with -leading zeroes. -) -pindex(OVERSTRIKE) -cindex(editor, overstrike mode) -cindex(overstrike mode, of editor) -item(tt(OVERSTRIKE))( -Start up the line editor in overstrike mode. -) pindex(PATH_DIRS) cindex(path search, extended) item(tt(PATH_DIRS) (tt(-Q)))( @@ -906,32 +753,6 @@ executables specified in this form. This takes place before any search indicated by this option, and regardless of whether `tt(.)' or the current directory appear in the command search path. ) -pindex(POSIX_BUILTINS) -item(tt(POSIX_BUILTINS) )( -When this option is set the tt(command) builtin can be used to execute -shell builtin commands. Parameter assignments specified before shell -functions and special builtins are kept after the command completes unless -the special builtin is prefixed with the tt(command) builtin. Special -builtins are -tt(.), -tt(:), -tt(break), -tt(continue), -tt(declare), -tt(eval), -tt(exit), -tt(export), -tt(integer), -tt(local), -tt(readonly), -tt(return), -tt(set), -tt(shift), -tt(source), -tt(times), -tt(trap) and -tt(unset). -) pindex(PRINT_EIGHT_BIT) cindex(eight bit characters, printing) item(tt(PRINT_EIGHT_BIT))( @@ -939,27 +760,118 @@ Print eight bit characters literally in completion lists, etc. This option is not necessary if your system correctly returns the printability of eight bit characters (see manref(ctype)(3)). ) -pindex(PRINT_EXIT_VALUE) -cindex(exit status, printing) -item(tt(PRINT_EXIT_VALUE) (tt(-1)))( -Print the exit value of programs with non-zero exit status. +pindex(PRINT_EXIT_VALUE) +cindex(exit status, printing) +item(tt(PRINT_EXIT_VALUE) (tt(-1)))( +Print the exit value of programs with non-zero exit status. +) +pindex(RC_QUOTES) +cindex(rc, quoting style) +cindex(quoting style, rc) +item(tt(RC_QUOTES))( +Allow the character sequence `tt('')' to signify a single quote +within singly quoted strings. Note this does not apply in quoted strings +using the format tt($')var(...)tt('), where a backslashed single quote can +be used. +) +pindex(RM_STAR_SILENT) +cindex(rm *, querying before) +cindex(querying before rm *) +item(tt(RM_STAR_SILENT) (tt(-H)) )( +Do not query the user before executing `tt(rm *)' or `tt(rm path/*)'. +) +pindex(RM_STAR_WAIT) +cindex(rm *, waiting before) +cindex(waiting before rm *) +item(tt(RM_STAR_WAIT))( +If querying the user before executing `tt(rm *)' or `tt(rm path/*)', +first wait ten seconds and ignore anything typed in that time. +This avoids the problem of reflexively answering `yes' to the query +when one didn't really mean it. The wait and query can always be +avoided by expanding the `tt(*)' in ZLE (with tab). +) +pindex(SHORT_LOOPS) +item(tt(SHORT_LOOPS) )( +Allow the short forms of tt(for), tt(repeat), tt(select), +tt(if), and tt(function) constructs. +) +pindex(SUN_KEYBOARD_HACK) +cindex(sun keyboard, annoying) +cindex(annoying keyboard, sun) +item(tt(SUN_KEYBOARD_HACK) (tt(-L)))( +If a line ends with a backquote, and there are an odd number +of backquotes on the line, ignore the trailing backquote. +This is useful on some keyboards where the return key is +too small, and the backquote key lies annoyingly close to it. +) +enditem() + +subsect(Job Control) +startitem() +pindex(AUTO_CONTINUE) +cindex(jobs, continuing automatically) +cindex(continuing jobs automatically) +item(tt(AUTO_CONTINUE))( +With this option set, stopped jobs that are removed from the job table +with the tt(disown) builtin command are automatically sent a tt(CONT) +signal to make them running. +) +pindex(AUTO_RESUME) +cindex(jobs, resuming automatically) +cindex(resuming jobs automatically) +item(tt(AUTO_RESUME) (tt(-W)))( +Treat single word simple commands without redirection +as candidates for resumption of an existing job. +) +pindex(BG_NICE) +cindex(jobs, background priority) +cindex(background jobs, priority of) +cindex(priority of background jobs) +item(tt(BG_NICE) (tt(-6)) )( +Run all background jobs at a lower priority. This option +is set by default. +) +pindex(CHECK_JOBS) +cindex(exiting, checking jobs when) +cindex(logging out, checking jobs when) +item(tt(CHECK_JOBS) )( +Report the status of background and suspended jobs before exiting a shell +with job control; a second attempt to exit the shell will succeed. +tt(NO_CHECK_JOBS) is best used only in combination with tt(NO_HUP), else +such jobs will be killed automatically. + +The check is omitted if the commands run from the previous command line +included a `tt(jobs)' command, since it is assumed the user is aware that +there are background or suspended jobs. A `tt(jobs)' command run from the +tt(precmd) function is not counted for this purpose. +) +pindex(HUP) +cindex(jobs, HUP) +item(tt(HUP) )( +Send the tt(HUP) signal to running jobs when the +shell exits. +) +pindex(LONG_LIST_JOBS) +cindex(jobs, list format) +item(tt(LONG_LIST_JOBS) (tt(-R)))( +List jobs in the long format by default. +) +pindex(MONITOR) +cindex(job control, allowing) +item(tt(MONITOR) (tt(-m), ksh: tt(-m)))( +Allow job control. Set by default in interactive shells. ) -pindex(PRIVILEGED) -cindex(privileged mode) -cindex(mode, privileged) -item(tt(PRIVILEGED) (tt(-p), ksh: tt(-p)))( -Turn on privileged mode. This is enabled automatically on startup if the -effective user (group) ID is not equal to the real user (group) ID. Turning -this option off causes the effective user and group IDs to be set to the -real user and group IDs. This option disables sourcing user startup files. -If zsh is invoked as `tt(sh)' or `tt(ksh)' with this option set, -tt(/etc/suid_profile) is sourced (after tt(/etc/profile) on interactive -shells). Sourcing tt(~/.profile) is disabled and the contents of the -tt(ENV) variable is ignored. This option cannot be changed using the -tt(-m) option of tt(setopt) and tt(unsetopt), and changing it inside a -function always changes it globally regardless of the tt(LOCAL_OPTIONS) -option. +pindex(NOTIFY) +cindex(background jobs, notification) +cindex(notification of background jobs) +item(tt(NOTIFY) (tt(-5), ksh: tt(-b)) )( +Report the status of background jobs immediately, rather than +waiting until just before printing a prompt. ) +enditem() + +subsect(Prompting) +startitem() pindex(PROMPT_BANG) cindex(prompt, ! expansion) item(tt(PROMPT_BANG) )( @@ -985,110 +897,233 @@ item(tt(PROMPT_SUBST) )( If set, em(parameter expansion), em(command substitution) and em(arithmetic expansion) are performed in prompts. ) -pindex(PUSHD_IGNORE_DUPS) -cindex(directory stack, ignoring duplicates) -item(tt(PUSHD_IGNORE_DUPS))( -Don't push multiple copies of the same directory onto the directory stack. +pindex(TRANSIENT_RPROMPT) +item(tt(TRANSIENT_RPROMPT))( +Remove any right prompt from display when accepting a command +line. This may be useful with terminals with other cut/paste methods. ) -pindex(PUSHD_MINUS) -cindex(directory stack, controlling syntax) -item(tt(PUSHD_MINUS))( -Exchanges the meanings of `tt(PLUS())' and `tt(-)' -when used with a number to specify a directory in the stack. +enditem() + +subsect(Scripts and Functions) +startitem() +pindex(C_BASES) +cindex(bases, output in C format) +cindex(hexadecimal, output in C format) +cindex(octal, output in C format) +item(tt(C_BASES))( +Output hexadecimal numbers in the standard C format, for example `tt(0xFF)' +instead of the usual `tt(16#FF)'. If the option tt(OCTAL_ZEROES) is also +set (it is not by default), octal numbers will be treated similarly and +hence appear as `tt(077)' instead of `tt(8#77)'. This option has no effect +on the choice of the output base, nor on the output of bases other than +hexadecimal and octal. Note that these formats will be understood on input +irrespective of the setting of tt(C_BASES). ) -pindex(PUSHD_SILENT) -cindex(directory stack, silencing) -item(tt(PUSHD_SILENT) (tt(-E)))( -Do not print the directory stack after tt(pushd) or tt(popd). +pindex(ERR_EXIT) +cindex(exit status, trapping) +item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( +If a command has a non-zero exit status, execute the tt(ZERR) +trap, if set, and exit. This is disabled while running initialization +scripts. ) -pindex(PUSHD_TO_HOME) -cindex(pushd, to home) -item(tt(PUSHD_TO_HOME) (tt(-D)))( -Have tt(pushd) with no arguments act like `tt(pushd $HOME)'. +pindex(ERR_RETURN) +cindex(function return, on error) +cidnex(return from function, on error) +item(tt(ERR_RETURN))( +If a command has a non-zero exit status, return immediately from the +enclosing function. The logic is identical to that for tt(ERR_EXIT), +except that an implicit tt(return) statement is executed instead of an +tt(exit). This will trigger an exit at the outermost level of a +non-interactive script. ) -pindex(RC_EXPAND_PARAM) -cindex(rc, parameter expansion style) -cindex(parameter expansion style, rc) -item(tt(RC_EXPAND_PARAM) (tt(-P)))( -Array expansions of the form -`var(foo)tt(${)var(xx)tt(})var(bar)', where the parameter -var(xx) is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with -`var(fooabar foobbar foocbar)' instead of the default -`var(fooa b cbar)'. +pindex(EXEC) +cindex(command execution, enabling) +item(tt(EXEC) (tt(PLUS()n), ksh: tt(PLUS()n)) )( +Do execute commands. Without this option, commands are +read and checked for syntax errors, but not executed. +This option cannot be turned off in an interactive shell, +except when `tt(-n)' is supplied to the shell at startup. ) -pindex(RC_QUOTES) -cindex(rc, quoting style) -cindex(quoting style, rc) -item(tt(RC_QUOTES))( -Allow the character sequence `tt('')' to signify a single quote -within singly quoted strings. Note this does not apply in quoted strings -using the format tt($')var(...)tt('), where a backslashed single quote can -be used. +pindex(FUNCTION_ARGZERO) +cindex($0, setting) +item(tt(FUNCTION_ARGZERO) )( +When executing a shell function or sourcing a script, set tt($0) +temporarily to the name of the function/script. ) -pindex(RCS) -cindex(startup files, sourcing) -item(tt(RCS) (tt(PLUS()f)) )( -After tt(/etc/zshenv) is sourced on startup, source the -tt(.zshenv), tt(/etc/zprofile), tt(.zprofile), -tt(/etc/zshrc), tt(.zshrc), tt(/etc/zlogin), tt(.zlogin), and tt(.zlogout) -files, as described in noderef(Files). -If this option is unset, the tt(/etc/zshenv) file is still sourced, but any -of the others will not be; it can be set at any time to prevent the -remaining startup files after the currently executing one from -being sourced. +pindex(LOCAL_OPTIONS) +item(tt(LOCAL_OPTIONS) )( +If this option is set at the point of return from a shell function, +all the options (including this one) which were in force upon entry to +the function are restored. Otherwise, only this option and the +tt(XTRACE) and tt(PRINT_EXIT_VALUE) options are restored. Hence +if this is explicitly unset by a shell function the other options in +force at the point of return will remain so. +A shell function can also guarantee itself a known shell configuration +with a formulation like `tt(emulate -L zsh)'; the tt(-L) activates +tt(LOCAL_OPTIONS). ) -pindex(REC_EXACT) -cindex(completion, exact matches) -item(tt(REC_EXACT) (tt(-S)))( -In completion, recognize exact matches even -if they are ambiguous. +pindex(LOCAL_TRAPS) +item(tt(LOCAL_TRAPS) )( +If this option is set when a signal trap is set inside a function, then the +previous status of the trap for that signal will be restored when the +function exits. Note that this option must be set em(prior) to altering the +trap behaviour in a function; unlike tt(LOCAL_OPTIONS), the value on exit +from the function is irrelevant. However, it does not need to be set +before any global trap for that to be correctly restored by a function. +For example, + +example(unsetopt localtraps +trap - INT +fn() { setopt localtraps; trap '' INT; sleep 3; }) + +will restore normally handling of tt(SIGINT) after the function exits. ) -pindex(RESTRICTED) -cindex(restricted shell) -item(tt(RESTRICTED) (tt(-r)))( -Enables restricted mode. This option cannot be changed using -tt(unsetopt), and setting it inside a function always changes it -globally regardless of the tt(LOCAL_OPTIONS) option. See -noderef(Restricted Shell). +pindex(MULTIOS) +item(tt(MULTIOS) )( +Perform implicit bf(tee)s or bf(cat)s when multiple +redirections are attempted (see noderef(Redirection)). +) +pindex(OCTAL_ZEROES) +cindex(octal, arithmetic expressions) +item(tt(OCTAL_ZEROES) )( +Interpret any integer constant beginning with a 0 as octal, per IEEE Std +1003.2-1992 (ISO 9945-2:1993). This is not enabled by default as it +causes problems with parsing of, for example, date and time strings with +leading zeroes. +) +pindex(TYPESET_SILENT) +item(tt(TYPESET_SILENT))( +If this is unset, executing any of the `tt(typeset)' family of +commands with no options and a list of parameters that have no values +to be assigned but already exist will display the value of the parameter. +If the option is set, they will only be shown when parameters are selected +with the `tt(-m)' option. The option `tt(-p)' is available whether or not +the option is set. +) +pindex(VERBOSE) +cindex(tracing, of input lines) +cindex(input, tracing) +item(tt(VERBOSE) (tt(-v), ksh: tt(-v)))( +Print shell input lines as they are read. +) +pindex(XTRACE) +cindex(tracing, of commands) +cindex(commands, tracing) +item(tt(XTRACE) (tt(-x), ksh: tt(-x)))( +Print commands and their arguments as they are executed. +) +enditem() + +subsect(Shell Emulation) +startitem() +pindex(BSD_ECHO) +cindex(echo, BSD compatible) +item(tt(BSD_ECHO) )( +Make the tt(echo) builtin compatible with the BSD manref(echo)(1) command. +This disables backslashed escape sequences in echo strings unless the +tt(-e) option is specified. +) +pindex(CSH_JUNKIE_HISTORY) +cindex(csh, history style) +cindex(history style, csh) +item(tt(CSH_JUNKIE_HISTORY) )( +A history reference without an event specifier will always refer to the +previous command. Without this option, such a history reference refers +to the same event as the previous history reference, defaulting to the +previous command. +) +pindex(CSH_JUNKIE_LOOPS) +cindex(csh, loop style) +cindex(loop style, csh) +item(tt(CSH_JUNKIE_LOOPS) )( +Allow loop bodies to take the form `var(list); tt(end)' instead of +`tt(do) var(list); tt(done)'. +) +pindex(CSH_JUNKIE_QUOTES) +cindex(csh, quoting style) +cindex(quoting style, csh) +item(tt(CSH_JUNKIE_QUOTES) )( +Changes the rules for single- and double-quoted text to match that of +bf(csh). These require that embedded newlines be preceded by a backslash; +unescaped newlines will cause an error message. +In double-quoted strings, it is made impossible to escape `tt($)', `tt(`)' +or `tt(")' (and `tt(\)' itself no longer needs escaping). +Command substitutions are only expanded once, and cannot be nested. +) +pindex(CSH_NULLCMD) +vindex(NULLCMD, ignoring) +vindex(READNULLCMD, ignoring) +cindex(redirections with no command, csh) +cindex(csh, redirections with no command) +item(tt(CSH_NULLCMD) )( +Do not use the values of tt(NULLCMD) and tt(READNULLCMD) +when running redirections with no command. This make +such redirections fail (see noderef(Redirection)). +) +pindex(KSH_ARRAYS) +cindex(arrays, ksh style) +cindex(array style, ksh) +cindex(ksh, array style) +item(tt(KSH_ARRAYS) )( +Emulate bf(ksh) array handling as closely as possible. If this option +is set, array elements are numbered from zero, an array parameter +without subscript refers to the first element instead of the whole array, +and braces are required to delimit a subscript (`tt(${path[2]})' rather +than just `tt($path[2])'). +) +pindex(KSH_AUTOLOAD) +item(tt(KSH_AUTOLOAD) )( +Emulate bf(ksh) function autoloading. This means that when a function is +autoloaded, the corresponding file is merely executed, and must define +the function itself. (By default, the function is defined to the contents +of the file. However, the most common bf(ksh)-style case - of the file +containing only a simple definition of the function - is always handled +in the bf(ksh)-compatible manner.) ) -pindex(RM_STAR_SILENT) -cindex(rm *, querying before) -cindex(querying before rm *) -item(tt(RM_STAR_SILENT) (tt(-H)) )( -Do not query the user before executing `tt(rm *)' or `tt(rm path/*)'. +pindex(KSH_OPTION_PRINT) +cindex(option printing, ksh style) +cindex(option printing style, ksh) +cindex(ksh, option printing style) +item(tt(KSH_OPTION_PRINT) )( +Alters the way options settings are printed: instead of separate lists of +set and unset options, all options are shown, marked `on' if +they are in the non-default state, `off' otherwise. ) -pindex(RM_STAR_WAIT) -cindex(rm *, waiting before) -cindex(waiting before rm *) -item(tt(RM_STAR_WAIT))( -If querying the user before executing `tt(rm *)' or `tt(rm path/*)', -first wait ten seconds and ignore anything typed in that time. -This avoids the problem of reflexively answering `yes' to the query -when one didn't really mean it. The wait and query can always be -avoided by expanding the `tt(*)' in ZLE (with tab). +pindex(KSH_TYPESET) +cindex(argument splitting, in typeset etc.) +cindex(ksh, argument splitting in typeset) +item(tt(KSH_TYPESET) )( +Alters the way arguments to the tt(typeset) family of commands, including +tt(declare), tt(export), tt(float), tt(integer), tt(local) and +tt(readonly), are processed. Without this option, zsh will perform normal +word splitting after command and parameter expansion in arguments of an +assignment; with it, word splitting does not take place in those cases. ) -pindex(SHARE_HISTORY) -cindex(share history) -cindex(history, sharing) -item(tt(SHARE_HISTORY) )( - -This option both imports new commands from the history file, and also -causes your typed commands to be appended to the history file (the -latter is like specifying tt(INC_APPEND_HISTORY)). -The history lines are also output with timestamps ala -tt(EXTENDED_HISTORY) (which makes it easier to find the spot where -we left off reading the file after it gets re-written). - -By default, history movement commands visit the imported lines as -well as the local lines, but you can toggle this on and off with the -set-local-history zle binding. It is also possible to create a zle -widget that will make some commands ignore imported commands, and -some include them. - -If you find that you want more control over when commands -get imported, you may wish to turn tt(SHARE_HISTORY) off, -tt(INC_APPEND_HISTORY) on, and then manually import -commands whenever you need them using `tt(fc -RI)'. +pindex(POSIX_BUILTINS) +item(tt(POSIX_BUILTINS) )( +When this option is set the tt(command) builtin can be used to execute +shell builtin commands. Parameter assignments specified before shell +functions and special builtins are kept after the command completes unless +the special builtin is prefixed with the tt(command) builtin. Special +builtins are +tt(.), +tt(:), +tt(break), +tt(continue), +tt(declare), +tt(eval), +tt(exit), +tt(export), +tt(integer), +tt(local), +tt(readonly), +tt(return), +tt(set), +tt(shift), +tt(source), +tt(times), +tt(trap) and +tt(unset). ) pindex(SH_FILE_EXPANSION) cindex(sh, expansion style) @@ -1101,32 +1136,6 @@ If this option is unset, it is performed em(after) brace expansion, so things like `tt(~$USERNAME)' and `tt(~{pfalstad,rc})' will work. ) -pindex(SH_GLOB) -cindex(sh, globbing style) -cindex(globbing style, sh) -item(tt(SH_GLOB) )( -Disables the special meaning of `tt(LPAR())', `tt(|)', `tt(RPAR())' -and 'tt(<)' for globbing the result of parameter and command substitutions, -and in some other places where -the shell accepts patterns. This option is set by default if zsh is -invoked as tt(sh) or tt(ksh). -) -pindex(SHIN_STDIN) -item(tt(SHIN_STDIN) (tt(-s), ksh: tt(-s)))( -Commands are being read from the standard input. -Commands are read from standard input if no command is specified with -tt(-c) and no file of commands is specified. If tt(SHIN_STDIN) -is set explicitly on the command line, -any argument that would otherwise have been -taken as a file to run will instead be treated as a normal positional -parameter. -Note that setting or unsetting this option on the command line does not -necessarily affect the state the option will have while the shell is -running - that is purely an indicator of whether on not commands are -em(actually) being read from standard input. -The value of this option cannot be changed anywhere other -than the command line. -) pindex(SH_NULLCMD) vindex(NULLCMD, ignoring) vindex(READNULLCMD, ignoring) @@ -1148,11 +1157,6 @@ If this option is set the shell tries to interpret single letter options (which are used with tt(set) and tt(setopt)) like bf(ksh) does. This also affects the value of the tt(-) special parameter. ) -pindex(SHORT_LOOPS) -item(tt(SHORT_LOOPS) )( -Allow the short forms of tt(for), tt(repeat), tt(select), -tt(if), and tt(function) constructs. -) pindex(SH_WORD_SPLIT) cindex(field splitting, sh style) cindex(sh, field splitting style) @@ -1161,6 +1165,73 @@ Causes field splitting to be performed on unquoted parameter expansions. Note that this option has nothing to do with word splitting. (See noderef(Parameter Expansion).) ) +pindex(TRAPS_ASYNC) +cindex(traps, asynchronous) +item(tt(TRAPS_ASYNC))( +While waiting for a program to exit, handle signals and run traps +immediately. Otherwise the trap is run after a child process has exited. +Note this does not affect the point at which traps are run for any case +other than when the shell is waiting for a child process. +) +enditem() + +subsect(Shell State) +startitem() +pindex(INTERACTIVE) +item(tt(INTERACTIVE) (tt(-i), ksh: tt(-i)))( +This is an interactive shell. This option is set upon initialisation if +the standard input is a tty and commands are being read from standard input. +(See the discussion of tt(SHIN_STDIN).) +This heuristic may be overridden by specifying a state for this option +on the command line. +The value of this option cannot be changed anywhere other than the command line. +) +pindex(LOGIN) +item(tt(LOGIN) (tt(-l), ksh: tt(-l)))( +This is a login shell. +If this option is not explicitly set, the shell is a login shell if +the first character of the tt(argv[0]) passed to the shell is a `tt(-)'. +) +pindex(PRIVILEGED) +cindex(privileged mode) +cindex(mode, privileged) +item(tt(PRIVILEGED) (tt(-p), ksh: tt(-p)))( +Turn on privileged mode. This is enabled automatically on startup if the +effective user (group) ID is not equal to the real user (group) ID. Turning +this option off causes the effective user and group IDs to be set to the +real user and group IDs. This option disables sourcing user startup files. +If zsh is invoked as `tt(sh)' or `tt(ksh)' with this option set, +tt(/etc/suid_profile) is sourced (after tt(/etc/profile) on interactive +shells). Sourcing tt(~/.profile) is disabled and the contents of the +tt(ENV) variable is ignored. This option cannot be changed using the +tt(-m) option of tt(setopt) and tt(unsetopt), and changing it inside a +function always changes it globally regardless of the tt(LOCAL_OPTIONS) +option. +) +pindex(RESTRICTED) +cindex(restricted shell) +item(tt(RESTRICTED) (tt(-r)))( +Enables restricted mode. This option cannot be changed using +tt(unsetopt), and setting it inside a function always changes it +globally regardless of the tt(LOCAL_OPTIONS) option. See +noderef(Restricted Shell). +) +pindex(SHIN_STDIN) +item(tt(SHIN_STDIN) (tt(-s), ksh: tt(-s)))( +Commands are being read from the standard input. +Commands are read from standard input if no command is specified with +tt(-c) and no file of commands is specified. If tt(SHIN_STDIN) +is set explicitly on the command line, +any argument that would otherwise have been +taken as a file to run will instead be treated as a normal positional +parameter. +Note that setting or unsetting this option on the command line does not +necessarily affect the state the option will have while the shell is +running - that is purely an indicator of whether on not commands are +em(actually) being read from standard input. +The value of this option cannot be changed anywhere other +than the command line. +) pindex(SINGLE_COMMAND) cindex(single command) pindex(INTERACTIVE, use of) @@ -1170,55 +1241,35 @@ has been executed. This also makes the shell non-interactive, unless the tt(INTERACTIVE) option is explicitly set on the command line. The value of this option cannot be changed anywhere other than the command line. ) +enditem() + +subsect(Zle) +startitem() +pindex(BEEP) +cindex(beep, enabling) +cindex(enabling the beep) +item(tt(BEEP) (tt(PLUS()B)) )( +Beep on error in ZLE. +) +pindex(EMACS) +item(tt(EMACS))( +If ZLE is loaded, turning on this option has the equivalent effect +of `tt(bindkey -e)'. In addition, the VI option is unset. +Turning it off has no effect. The option setting is +not guaranteed to reflect the current keymap. This option is +provided for compatibility; tt(bindkey) is the recommended interface. +) +pindex(OVERSTRIKE) +cindex(editor, overstrike mode) +cindex(overstrike mode, of editor) +item(tt(OVERSTRIKE))( +Start up the line editor in overstrike mode. +) pindex(SINGLE_LINE_ZLE) cindex(editor, single line mode) item(tt(SINGLE_LINE_ZLE) (tt(-M)) )( Use single-line command line editing instead of multi-line. ) -pindex(SUN_KEYBOARD_HACK) -cindex(sun keyboard, annoying) -cindex(annoying keyboard, sun) -item(tt(SUN_KEYBOARD_HACK) (tt(-L)))( -If a line ends with a backquote, and there are an odd number -of backquotes on the line, ignore the trailing backquote. -This is useful on some keyboards where the return key is -too small, and the backquote key lies annoyingly close to it. -) -pindex(TRANSIENT_RPROMPT) -item(tt(TRANSIENT_RPROMPT))( -Remove any right prompt from display when accepting a command -line. This may be useful with terminals with other cut/paste methods. -) -pindex(TRAPS_ASYNC) -cindex(traps, asynchronous) -item(tt(TRAPS_ASYNC))( -While waiting for a program to exit, handle signals and run traps -immediately. Otherwise the trap is run after a child process has exited. -Note this does not affect the point at which traps are run for any case -other than when the shell is waiting for a child process. -) -pindex(TYPESET_SILENT) -item(tt(TYPESET_SILENT))( -If this is unset, executing any of the `tt(typeset)' family of -commands with no options and a list of parameters that have no values -to be assigned but already exist will display the value of the parameter. -If the option is set, they will only be shown when parameters are selected -with the `tt(-m)' option. The option `tt(-p)' is available whether or not -the option is set. -) -pindex(UNSET) -cindex(parameters, substituting unset) -cindex(unset parameters, substituting) -item(tt(UNSET) (tt(PLUS()u), ksh: tt(PLUS()u)) )( -Treat unset parameters as if they were empty when substituting. -Otherwise they are treated as an error. -) -pindex(VERBOSE) -cindex(tracing, of input lines) -cindex(input, tracing) -item(tt(VERBOSE) (tt(-v), ksh: tt(-v)))( -Print shell input lines as they are read. -) pindex(VI) item(tt(VI))( If ZLE is loaded, turning on this option has the equivalent effect @@ -1227,12 +1278,6 @@ Turning it off has no effect. The option setting is not guaranteed to reflect the current keymap. This option is provided for compatibility; tt(bindkey) is the recommended interface. ) -pindex(XTRACE) -cindex(tracing, of commands) -cindex(commands, tracing) -item(tt(XTRACE) (tt(-x), ksh: tt(-x)))( -Print commands and their arguments as they are executed. -) pindex(ZLE) cindex(editor, enabling) cindex(enabling the editor) @@ -1241,6 +1286,7 @@ Use the zsh line editor. Set by default in interactive shells connected to a terminal. ) enditem() + texinode(Option Aliases)(Single Letter Options)(Description of Options)(Options) sect(Option Aliases) cindex(options, aliases) -- cgit 1.4.1