commit bash-20200520 snapshot

doc/shell-compat

@@ -0,0 +1,158 @@
+@node Shell Compatibility Mode
+@section Shell Compatibility Mode
+@cindex Compatibility Level
+@cindex Compatibility Mode
+
+Bash-4.0 introduced the concept of a `shell compatibility level', specified
+as a set of options to the shopt builtin
+(@code{compat31},
+@code{compat32},
+@code{compat40},
+@code{compat41},
+and so on).
+There is only one current
+compatibility level -- each option is mutually exclusive.
+The compatibility level is intended to allow users to select behavior
+from previous versions that is incompatible with newer versions
+while they migrate scripts to use current features and
+behavior. It's intended to be a temporary solution.
+
+This section does not mention behavior that is standard for a particular
+version (e.g., setting @code{compat32} means that quoting the rhs of the regexp
+matching operator quotes special regexp characters in the word, which is
+default behavior in bash-3.2 and above). 
+
+If a user enables, say, @code{compat32}, it may affect the behavior of other
+compatibility levels up to and including the current compatibility level.
+The idea is that each compatibility level controls behavior that changed
+in that version of Bash, but that granularity may not be sufficient for
+all uses, and as a result users should employ compatibility levels carefully.
+Read the documentation for a particular feature to find out the
+current behavior.
+
+Bash-4.3 introduced a new shell variable: @env{BASH_COMPAT}.
+The value assigned
+to this variable (a decimal version number like 4.2, or an integer
+corresponding to the @code{compat}@var{NN} option, like 42) determines the
+compatibility level.
+
+Starting with bash-4.4, Bash has begun deprecating older compatibility
+levels.
+Eventually, the options will be removed in favor of @env{BASH_COMPAT}.
+
+Bash-5.0 is the final version for which there will be an individual shopt
+option for the previous version. Users should use @env{BASH_COMPAT}
+on bash-5.0 and later versions.
+
+The following table describes the behavior changes controlled by each
+compatibility level setting.
+The @code{compat}@var{NN} tag is used as shorthand for setting the
+compatibility level
+to @var{NN} using one of the following mechanisms.
+For versions prior to bash-5.0, the compatibility level may be set using
+the corresponding @code{compat}@var{NN} shopt option.
+For bash-4.3 and later versions, the @env{BASH_COMPAT} variable is preferred,
+and it is required for bash-5.1 and later versions.
+
+@table @code
+@item compat31
+@itemize @bullet
+@item
+quoting the rhs of the @code{[[} command's regexp matching operator (=~)
+has no special effect
+@end itemize
+
+@item compat32
+@itemize @bullet
+@item
+interrupting a command list such as "a ; b ; c" causes the execution
+of the next command in the list (in bash-4.0 and later versions,
+the shell acts as if it received the interrupt, so
+interrupting one command in a list aborts the execution of the
+entire list)
+@end itemize
+
+@item compat40
+@itemize @bullet
+@item
+the @samp{<} and @samp{>} operators to the @code{[[} command do not
+consider the current locale when comparing strings; they use ASCII
+ordering.
+Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
+bash-4.1 and later use the current locale's collation sequence and
+strcoll(3).
+@end itemize
+
+@item compat41
+@itemize @bullet
+@item
+in posix mode, @code{time} may be followed by options and still be
+recognized as a reserved word (this is @sc{posix} interpretation 267)
+@item
+in posix mode, the parser requires that an even number of single
+quotes occur in the @var{word} portion of a double-quoted $@{@dots{}@}
+parameter expansion and treats them specially, so that characters within
+the single quotes are considered quoted
+(this is @sc{posix} interpretation 221)
+@end itemize
+
+@item compat42
+@itemize @bullet
+@item
+the replacement string in double-quoted pattern substitution is not
+run through quote removal, as it is in versions after bash-4.2
+@item
+in posix mode, single quotes are considered special when expanding
+the @var{word} portion of a double-quoted a $@{@dots{}@} parameter expansion
+and can be used to quote a closing brace or other special character
+(this is part of @sc{posix} interpretation 221);
+in later versions, single quotes
+are not special within double-quoted word expansions
+@end itemize
+
+@item compat43
+@itemize @bullet
+@item
+the shell does not print a warning message if an attempt is made to
+use a quoted compound assignment as an argument to declare
+(declare -a foo='(1 2)'). Later versions warn that this usage is
+deprecated
+@item
+word expansion errors are considered non-fatal errors that cause the
+current command to fail, even in posix mode
+(the default behavior is to make them fatal errors that cause the shell
+to exit)
+@item
+when executing a shell function, the loop state (while/until/etc.)
+is not reset, so @code{break} or @code{continue} in that function will break
+or continue loops in the calling context. Bash-4.4 and later reset
+the loop state to prevent this
+@end itemize
+
+@item compat44
+@itemize @bullet
+@item
+the shell sets up the values used by @env{BASH_ARGV} and @env{BASH_ARGC}
+so they can expand to the shell's positional parameters even if extended
+debug mode is not enabled
+@item
+a subshell inherits loops from its parent context, so @code{break}
+or @code{continue} will cause the subshell to exit.
+Bash-5.0 and later reset the loop state to prevent the exit
+@item
+variable assignments preceding builtins like @code{export} and @code{readonly}
+that set attributes continue to affect variables with the same
+name in the calling environment even if the shell is not in posix
+mode
+@end itemize
+
+@item compat50 (set using BASH_COMPAT)
+@itemize @bullet
+@item
+Bash-5.1 changed the way @code{$RANDOM} is generated to introduce slightly
+more randomness. If the shell compatibility level is set to 50 or
+lower, it reverts to the method from bash-5.0 and previous versions,
+so seeding the random number generator by assigning a value to
+@env{RANDOM} wll produce the same sequence as in bash-5.0
+@end itemize
+@end table