bash-5.0-beta release

doc/bash.1

@@ -5,12 +5,12 @@
 .\"	Case Western Reserve University
 .\"	chet.ramey@case.edu
 .\"
-.\"	Last Change: Thu Mar 15 11:30:03 EDT 2018
+.\"	Last Change: Tue Aug  7 12:01:07 EDT 2018
 .\"
 .\" bash_builtins, strip all but Built-Ins section
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
-.TH BASH 1 "2018 March 15" "GNU Bash 5.0"
+.TH BASH 1 "2018 August 7" "GNU Bash 5.0"
 .\"
 .\" There's some problem with having a `@'
 .\" in a tagged paragraph with the BSD man macros.
@@ -739,7 +739,7 @@ to be matched as a string.
 An additional binary operator, \fB=~\fP, is available, with the same
 precedence as \fB==\fP and \fB!=\fP.
 When it is used, the string to the right of the operator is considered
-an extended regular expression and matched accordingly (as in \fIregex\fP(3)).
+a POSIX extended regular expression and matched accordingly (as in \fIregex\fP(3)).
 The return value is 0 if the string matches
 the pattern, and 1 otherwise.
 If the regular expression is syntactically incorrect, the conditional
@@ -1357,7 +1357,14 @@ If
 is null, the parameters are joined without intervening separators.
 .TP
 .B @
-Expands to the positional parameters, starting from one.  When the
+Expands to the positional parameters, starting from one.
+In contexts where word splitting is performed, this expands each
+positional parameter to a separate word; if not within double
+quotes, these words are subject to word splitting.
+In contexts where word splitting is not performed,
+this expands to a single word
+with each positional parameter separated by a space.
+When the
 expansion occurs within double quotes, each parameter expands to a
 separate word.  That is, "\fB$@\fP" is equivalent to
 "\fB$1\fP" "\fB$2\fP" ...
@@ -1499,7 +1506,8 @@ only when in extended debugging mode (see the description of the
 option to the
 .B shopt
 builtin below).
-Setting \fBextdebug\fP after the shell has started to execute a script
+Setting \fBextdebug\fP after the shell has started to execute a script,
+or referencing this variable when \fBextdebug\fP is not set,
 may result in inconsistent values.
 .TP
 .B BASH_ARGV
@@ -1519,7 +1527,8 @@ only when in extended debugging mode
 option to the
 .B shopt
 builtin below).
-Setting \fBextdebug\fP after the shell has started to execute a script
+Setting \fBextdebug\fP after the shell has started to execute a script,
+or referencing this variable when \fBextdebug\fP is not set,
 may result in inconsistent values.
 .TP
 .B BASH_ARGV0
@@ -2072,7 +2081,7 @@ line editing.
 Similar to
 .SM
 .BR BASH_ENV ;
-used when the shell is invoked in POSIX mode.
+used when the shell is invoked in \fIposix mode\fP.
 .TP
 .B EXECIGNORE
 A colon-separated list of shell patterns (see \fBPattern Matching\fP)
@@ -2277,6 +2286,11 @@ startup file, overriding the default of
 .B READLINE
 below).
 .TP
+.B INSIDE_EMACS
+If this variable appears in the environment when the shell starts,
+\fBbash\fP assumes that it is running inside an Emacs shell buffer
+and may disable line editing, depending on the value of \fBTERM\fP.
+.TP
 .B LANG
 Used to determine the locale category for any category not specifically
 selected with a variable starting with \fBLC_\fP.
@@ -2400,6 +2414,8 @@ running, \fBbash\fP enables \fIposix mode\fP, as if the command
 .if t \f(CWset -o posix\fP
 .if n \fIset -o posix\fP
 had been executed.
+When the shell enters \fIposix mode\fP, it sets this variable if it was
+not already set.
 .TP
 .B PROMPT_COMMAND
 If set, the value is executed as a command prior to issuing each primary
@@ -2914,6 +2930,14 @@ and
 .SM
 .BR CDPATH ,
 and the shell assigns the expanded value.
+.PP
+Bash also performs tilde expansion on words satisfying the conditions of
+variable assignments (as described above under
+.SM
+.BR PARAMETERS )
+when they appear as arguments to simple commands.
+Bash does not do this, except for the \fIdeclaration\fP commands listed
+above, when in \fIposix mode\fP.
 .SS Parameter Expansion
 .PP
 The `\fB$\fP' character introduces parameter expansion,
@@ -2945,16 +2969,16 @@ The \fIparameter\fP is a shell parameter as described above
 .PP
 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
 and \fIparameter\fP is not a \fInameref\fP,
-it introduces a level of variable indirection.
-\fBBash\fP uses the value of the variable formed from the rest of
-\fIparameter\fP as the name of the variable; this variable is then
-expanded and that value is used in the rest of the substitution, rather
-than the value of \fIparameter\fP itself.
+it introduces a level of indirection.
+\fBBash\fP uses the value formed by expanding the rest of
+\fIparameter\fP as the new \fIparameter\fP; this is then
+expanded and that value is used in the rest of the expansion, rather
+than the expansion of the original \fIparameter\fP.
 This is known as \fIindirect expansion\fP.
 The value is subject to tilde expansion,
 parameter expansion, command substitution, and arithmetic expansion.
 If \fIparameter\fP is a nameref, this expands to the name of the
-variable referenced by \fIparameter\fP instead of performing the
+parameter referenced by \fIparameter\fP instead of performing the
 complete indirect expansion.
 The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
 ${\fB!\fP\fIname\fP[\fI@\fP]} described below.
@@ -4821,7 +4845,7 @@ subshell environment.  Changes made to the subshell environment
 cannot affect the shell's execution environment.
 .PP
 Subshells spawned to execute command substitutions inherit the value of
-the \fB\-e\fP option from the parent shell.  When not in \fIposix\fP mode,
+the \fB\-e\fP option from the parent shell.  When not in \fIposix mode\fP,
 \fBbash\fP clears the \fB\-e\fP option in such subshells.
 .PP
 If a command is followed by a \fB&\fP and job control is not active, the
@@ -7640,12 +7664,12 @@ will be displayed.
 The return value is true unless an invalid option is supplied, or no
 matches were generated.
 .TP
-\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DE\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
+\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
 .br
 [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
 .PD 0
 .TP
-\fBcomplete\fP \fB\-pr\fP [\fB\-DE\fP] [\fIname\fP ...]
+\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...]
 .PD
 Specify how arguments to each \fIname\fP should be completed.
 If the \fB\-p\fP option is supplied, or if no options are supplied,
@@ -7654,12 +7678,21 @@ them to be reused as input.
 The \fB\-r\fP option removes a completion specification for
 each \fIname\fP, or, if no \fIname\fPs are supplied, all
 completion specifications.
-The \fB\-D\fP option indicates that the remaining options and actions should
+The \fB\-D\fP option indicates that other supplied options and actions should
 apply to the ``default'' command completion; that is, completion attempted
 on a command for which no completion has previously been defined.
-The \fB\-E\fP option indicates that the remaining options and actions should
+The \fB\-E\fP option indicates that other supplied options and actions should
 apply to ``empty'' command completion; that is, completion attempted on a
 blank line.
+The \fB\-I\fP option indicates that other supplied options and actions should
+apply to completion on the inital non-assignment word on the line, or after
+a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
+name completion.
+If multiple options are supplied, the \fB\-D\fP option takes precedence
+over \fB\-E\fP, and both take precedence over \fB\-I\fP.
+If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
+\fIname\fP arguments are ignored; these completions only apply to the case
+specified by the option.
 .sp 1
 The process of applying these completion specifications when word completion
 is attempted is described above under \fBProgrammable Completion\fP.
@@ -7855,7 +7888,7 @@ a \fIname\fP for which no specification exists, or
 an error occurs adding a completion specification.
 .RE
 .TP
-\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DE\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
+\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
 Modify completion options for each \fIname\fP according to the
 \fIoption\fPs, or for the
 currently-executing completion if no \fIname\fPs are supplied.
@@ -7863,12 +7896,16 @@ If no \fIoption\fPs are given, display the completion options for each
 \fIname\fP or the current completion.
 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
 builtin described above.
-The \fB\-D\fP option indicates that the remaining options should
+The \fB\-D\fP option indicates that other supplied options should
 apply to the ``default'' command completion; that is, completion attempted
 on a command for which no completion has previously been defined.
-The \fB\-E\fP option indicates that the remaining options should
+The \fB\-E\fP option indicates that other supplied options should
 apply to ``empty'' command completion; that is, completion attempted on a
 blank line.
+The \fB\-I\fP option indicates that other supplied options should
+apply to completion on the inital non-assignment word on the line,
+or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually
+command name completion.
 .sp 1
 The return value is true unless an invalid option is supplied, an attempt
 is made to modify the options for a \fIname\fP for which no completion
@@ -9271,7 +9308,7 @@ Without options, the name and value of each shell variable are displayed
 in a format that can be reused as input
 for setting or resetting the currently-set variables.
 Read-only variables cannot be reset.
-In \fIposix\fP mode, only shell variables are listed.
+In \fIposix mode\fP, only shell variables are listed.
 The output is sorted according to the current locale.
 When options are specified, they set or unset shell attributes.
 Any arguments remaining after option processing are treated
@@ -9817,7 +9854,7 @@ interrupt; previous versions continue with the next command in the list.
 .B compat41
 If set,
 .BR bash ,
-when in \fIposix\fP mode, treats a single quote in a double-quoted
+when in \fIposix mode\fP, treats a single quote in a double-quoted
 parameter expansion as a special character.  The single quotes must match
 (an even number) and the characters between the single quotes are considered
 quoted.  This is the behavior of posix mode through version 4.1.
@@ -10589,7 +10626,7 @@ which is in units of 512-byte blocks;
 and
 .BR \-u ,
 which are unscaled values;
-and, when in Posix mode,
+and, when in posix mode,
 .B \-c
 and
 .BR \-f ,