changes to new pattern substitution replacement; documentation updates

doc/bashref.info

@@ -2,9 +2,9 @@ This is bashref.info, produced by makeinfo version 6.8 from
 bashref.texi.
 
 This text is a brief description of the features that are present in the
-Bash shell (version 5.1, 1 October 2021).
+Bash shell (version 5.1, 15 October 2021).
 
-   This is Edition 5.1, last updated 1 October 2021, of 'The GNU Bash
+   This is Edition 5.1, last updated 15 October 2021, of 'The GNU Bash
 Reference Manual', for 'Bash', Version 5.1.
 
    Copyright (C) 1988-2021 Free Software Foundation, Inc.
@@ -27,10 +27,10 @@ Bash Features
 *************
 
 This text is a brief description of the features that are present in the
-Bash shell (version 5.1, 1 October 2021).  The Bash home page is
+Bash shell (version 5.1, 15 October 2021).  The Bash home page is
 <http://www.gnu.org/software/bash/>.
 
-   This is Edition 5.1, last updated 1 October 2021, of 'The GNU Bash
+   This is Edition 5.1, last updated 15 October 2021, of 'The GNU Bash
 Reference Manual', for 'Bash', Version 5.1.
 
    Bash contains features that appear in other popular shells, and some
@@ -2078,10 +2078,13 @@ omitted, the operator tests only for existence.
 
      Any unquoted instances of '&' in STRING are replaced with the
      matching portion of PATTERN.  This is intended to duplicate a
-     common 'sed' idiom.  Backslash is used to quote '&' in STRING;
-     users should take care if STRING is double-quoted to avoid unwanted
-     interactions between the backslash and double-quoting.  For
-     instance,
+     common 'sed' idiom.  Backslash is used to quote '&' in STRING; the
+     backslash is removed in order to permit a literal '&' in the
+     replacement string.  Pattern substitution performs the check for
+     '&' after expanding STRING, so users should take care to quote
+     backslashes intended to escape the '&' and inhibit replacement so
+     they survive any quote removal performed by the expansion of
+     STRING.  For instance,
 
           var=abcdef
           echo ${var/abc/& }
@@ -2095,16 +2098,18 @@ omitted, the operator tests only for existence.
           echo "${var/abc/\& }"
           echo ${var/abc/"\& "}
 
-     will display two lines of "& def" and a third line of "\& def".
-     This is because '&' is not one of the characters for which
-     backslash is special in double quotes, and the expansion of STRING
-     is performed in a context that doesn't take the enclosing double
-     quotes into account.  It should rarely be necessary to enclose only
-     STRING in double quotes.
-
-     Pattern substitution performs the check for '&' before expanding
-     STRING to catch backslashes escaping the '&' before they are
-     removed by the expansion.
+     will display two lines of "abc def" and a third line of "& def".
+     The first two are replaced because the backslash is removed by
+     quote removal performed during the expansion of STRING (the
+     expansion is performed in a context that doesn't take any enclosing
+     double quotes into account, as with other word expansions).  In the
+     third case, the double quotes affect the expansion of '\&', and,
+     because '&' is not one of the characters for which backslash is
+     special in double quotes, the backslash survives the expansion,
+     inhibits the replacement, but is removed because it is treated
+     specially.  One could use '\\&', unquoted, as the replacement
+     string to achive the same effect.  It should rarely be necessary to
+     enclose only STRING in double quotes.
 
      If the 'nocasematch' shell option (see the description of 'shopt'
      in *note The Shopt Builtin::) is enabled, the match is performed
@@ -10184,20 +10189,28 @@ These are installation instructions for Bash.
   3. Optionally, type 'make tests' to run the Bash test suite.
 
   4. Type 'make install' to install 'bash' and 'bashbug'.  This will
-     also install the manual pages and Info file.
+     also install the manual pages and Info file, message translation
+     files, some supplemental documentation, a number of example
+     loadable builtin commands, and a set of header files for developing
+     loadable builtins.  You may need additional privileges to install
+     'bash' to your desired destination, so 'sudo make install' might be
+     required.  More information about controlling the locations where
+     'bash' and other files are installed is below (*note Installation
+     Names::).
 
    The 'configure' shell script attempts to guess correct values for
 various system-dependent variables used during compilation.  It uses
 those values to create a 'Makefile' in each directory of the package
-(the top directory, the 'builtins', 'doc', and 'support' directories,
-each directory under 'lib', and several others).  It also creates a
-'config.h' file containing system-dependent definitions.  Finally, it
-creates a shell script named 'config.status' that you can run in the
-future to recreate the current configuration, a file 'config.cache' that
-saves the results of its tests to speed up reconfiguring, and a file
-'config.log' containing compiler output (useful mainly for debugging
-'configure').  If at some point 'config.cache' contains results you
-don't want to keep, you may remove or edit it.
+(the top directory, the 'builtins', 'doc', 'po', and 'support'
+directories, each directory under 'lib', and several others).  It also
+creates a 'config.h' file containing system-dependent definitions.
+Finally, it creates a shell script named 'config.status' that you can
+run in the future to recreate the current configuration, a file
+'config.cache' that saves the results of its tests to speed up
+reconfiguring, and a file 'config.log' containing compiler output
+(useful mainly for debugging 'configure').  If at some point
+'config.cache' contains results you don't want to keep, you may remove
+or edit it.
 
    To find out more about the options and arguments that the 'configure'
 script understands, type
@@ -10228,7 +10241,7 @@ considered for the next release.
    The file 'configure.ac' is used to create 'configure' by a program
 called Autoconf.  You only need 'configure.ac' if you want to change it
 or regenerate 'configure' using a newer version of Autoconf.  If you do
-this, make sure you are using Autoconf version 2.50 or newer.
+this, make sure you are using Autoconf version 2.69 or newer.
 
    You can remove the program binaries and object files from the source
 code directory by typing 'make clean'.  To also remove the files that
@@ -10296,10 +10309,13 @@ File: bashref.info,  Node: Installation Names,  Next: Specifying the System Type
 =======================
 
 By default, 'make install' will install into '/usr/local/bin',
-'/usr/local/man', etc.  You can specify an installation prefix other
-than '/usr/local' by giving 'configure' the option '--prefix=PATH', or
-by specifying a value for the 'DESTDIR' 'make' variable when running
-'make install'.
+'/usr/local/man', etc.; that is, the "installation prefix" defaults to
+'/usr/local'.  You can specify an installation prefix other than
+'/usr/local' by giving 'configure' the option '--prefix=PATH', or by
+specifying a value for the 'prefix' 'make' variable when running 'make
+install' (e.g., 'make install prefix=PATH').  The 'prefix' variable
+provides a default for 'exec_prefix' and other variables used when
+installing bash.
 
    You can specify separate installation prefixes for
 architecture-specific files and architecture-independent files.  If you
@@ -10307,6 +10323,30 @@ give 'configure' the option '--exec-prefix=PATH', 'make install' will
 use PATH as the prefix for installing programs and libraries.
 Documentation and other data files will still use the regular prefix.
 
+   If you would like to change the installation locations for a single
+run, you can specify these variables as arguments to 'make': 'make
+install exec_prefix=/' will install 'bash' and 'bashbug' into '/bin'
+instead of the default '/usr/local/bin'.
+
+   If you want to see the files bash will install and where it will
+install them without changing anything on your system, specify the
+variable 'DESTDIR' as an argument to 'make'.  Its value should be the
+absolute directory path you'd like to use as the root of your sample
+installation tree.  For example,
+
+     mkdir /fs1/bash-install
+     make install DESTDIR=/fs1/bash-install
+
+will install 'bash' into '/fs1/bash-install/usr/local/bin/bash', the
+documentation into directories within
+'/fs1/bash-install/usr/local/share', the example loadable builtins into
+'/fs1/bash-install/usr/local/lib/bash', and so on.  You can use the
+usual 'exec_prefix' and 'prefix' variables to alter the directory paths
+beneath the value of 'DESTDIR'.
+
+   The GNU Makefile standards provide a more complete description of
+these variables and their effects.
+
 
 File: bashref.info,  Node: Specifying the System Type,  Next: Sharing Defaults,  Prev: Installation Names,  Up: Installing Bash
 
@@ -10460,15 +10500,21 @@ compiled, linked, and installed, rather than changing run-time features.
 following options, but it is processed first, so individual options may
 be enabled using 'enable-FEATURE'.
 
-   All of the following options except for 'disabled-builtins',
-'direxpand-default', 'strict-posix-default', and 'xpg-echo-default' are
-enabled by default, unless the operating system does not provide the
-necessary support.
+   All of the following options except for 'alt-array-implementation',
+'disabled-builtins', 'direxpand-default', 'strict-posix-default', and
+'xpg-echo-default' are enabled by default, unless the operating system
+does not provide the necessary support.
 
 '--enable-alias'
      Allow alias expansion and include the 'alias' and 'unalias'
      builtins (*note Aliases::).
 
+'--enable-alt-array-implementation'
+     This builds bash using an alternate implementation of arrays (*note
+     Arrays::) that provides faster access at the expense of using more
+     memory (sometimes many times more, depending on how sparse an array
+     is).
+
 '--enable-arith-for-command'
      Include support for the alternate form of the 'for' command that
      behaves like the C language 'for' statement (*note Looping
@@ -12292,138 +12338,138 @@ D.5 Concept Index
 
 
 Tag Table:
-Node: Top893
-Node: Introduction2809
-Node: What is Bash?3025
-Node: What is a shell?4139
-Node: Definitions6677
-Node: Basic Shell Features9628
-Node: Shell Syntax10847
-Node: Shell Operation11873
-Node: Quoting13166
-Node: Escape Character14470
-Node: Single Quotes14955
-Node: Double Quotes15303
-Node: ANSI-C Quoting16581
-Node: Locale Translation17891
-Node: Creating Internationalized Scripts19202
-Node: Comments23319
-Node: Shell Commands23937
-Node: Reserved Words24875
-Node: Simple Commands25631
-Node: Pipelines26285
-Node: Lists29244
-Node: Compound Commands31039
-Node: Looping Constructs32051
-Node: Conditional Constructs34546
-Node: Command Grouping48890
-Node: Coprocesses50368
-Node: GNU Parallel53031
-Node: Shell Functions53948
-Node: Shell Parameters61239
-Node: Positional Parameters65627
-Node: Special Parameters66529
-Node: Shell Expansions69743
-Node: Brace Expansion71870
-Node: Tilde Expansion74604
-Node: Shell Parameter Expansion77225
-Node: Command Substitution94537
-Node: Arithmetic Expansion95892
-Node: Process Substitution96860
-Node: Word Splitting97980
-Node: Filename Expansion99924
-Node: Pattern Matching102524
-Node: Quote Removal107132
-Node: Redirections107427
-Node: Executing Commands117087
-Node: Simple Command Expansion117757
-Node: Command Search and Execution119867
-Node: Command Execution Environment122245
-Node: Environment125280
-Node: Exit Status126943
-Node: Signals128727
-Node: Shell Scripts130694
-Node: Shell Builtin Commands133721
-Node: Bourne Shell Builtins135759
-Node: Bash Builtins157220
-Node: Modifying Shell Behavior188037
-Node: The Set Builtin188382
-Node: The Shopt Builtin198795
-Node: Special Builtins214224
-Node: Shell Variables215203
-Node: Bourne Shell Variables215640
-Node: Bash Variables217744
-Node: Bash Features250559
-Node: Invoking Bash251572
-Node: Bash Startup Files257585
-Node: Interactive Shells262688
-Node: What is an Interactive Shell?263098
-Node: Is this Shell Interactive?263747
-Node: Interactive Shell Behavior264562
-Node: Bash Conditional Expressions268075
-Node: Shell Arithmetic272717
-Node: Aliases275661
-Node: Arrays278274
-Node: The Directory Stack284283
-Node: Directory Stack Builtins285067
-Node: Controlling the Prompt289327
-Node: The Restricted Shell292292
-Node: Bash POSIX Mode294889
-Node: Shell Compatibility Mode306162
-Node: Job Control312818
-Node: Job Control Basics313278
-Node: Job Control Builtins318280
-Node: Job Control Variables323680
-Node: Command Line Editing324836
-Node: Introduction and Notation326507
-Node: Readline Interaction328130
-Node: Readline Bare Essentials329321
-Node: Readline Movement Commands331104
-Node: Readline Killing Commands332064
-Node: Readline Arguments333982
-Node: Searching335026
-Node: Readline Init File337212
-Node: Readline Init File Syntax338473
-Node: Conditional Init Constructs359753
-Node: Sample Init File363949
-Node: Bindable Readline Commands367073
-Node: Commands For Moving368277
-Node: Commands For History370328
-Node: Commands For Text375322
-Node: Commands For Killing378971
-Node: Numeric Arguments382004
-Node: Commands For Completion383143
-Node: Keyboard Macros387334
-Node: Miscellaneous Commands388021
-Node: Readline vi Mode393960
-Node: Programmable Completion394867
-Node: Programmable Completion Builtins402647
-Node: A Programmable Completion Example413342
-Node: Using History Interactively418589
-Node: Bash History Facilities419273
-Node: Bash History Builtins422278
-Node: History Interaction427286
-Node: Event Designators430906
-Node: Word Designators432260
-Node: Modifiers434020
-Node: Installing Bash435831
-Node: Basic Installation436968
-Node: Compilers and Options440226
-Node: Compiling For Multiple Architectures440967
-Node: Installation Names442660
-Node: Specifying the System Type443478
-Node: Sharing Defaults444194
-Node: Operation Controls444867
-Node: Optional Features445825
-Node: Reporting Bugs456625
-Node: Major Differences From The Bourne Shell457900
-Node: GNU Free Documentation License474750
-Node: Indexes499927
-Node: Builtin Index500381
-Node: Reserved Word Index507208
-Node: Variable Index509656
-Node: Function Index526148
-Node: Concept Index539932
+Node: Top895
+Node: Introduction2813
+Node: What is Bash?3029
+Node: What is a shell?4143
+Node: Definitions6681
+Node: Basic Shell Features9632
+Node: Shell Syntax10851
+Node: Shell Operation11877
+Node: Quoting13170
+Node: Escape Character14474
+Node: Single Quotes14959
+Node: Double Quotes15307
+Node: ANSI-C Quoting16585
+Node: Locale Translation17895
+Node: Creating Internationalized Scripts19206
+Node: Comments23323
+Node: Shell Commands23941
+Node: Reserved Words24879
+Node: Simple Commands25635
+Node: Pipelines26289
+Node: Lists29248
+Node: Compound Commands31043
+Node: Looping Constructs32055
+Node: Conditional Constructs34550
+Node: Command Grouping48894
+Node: Coprocesses50372
+Node: GNU Parallel53035
+Node: Shell Functions53952
+Node: Shell Parameters61243
+Node: Positional Parameters65631
+Node: Special Parameters66533
+Node: Shell Expansions69747
+Node: Brace Expansion71874
+Node: Tilde Expansion74608
+Node: Shell Parameter Expansion77229
+Node: Command Substitution95023
+Node: Arithmetic Expansion96378
+Node: Process Substitution97346
+Node: Word Splitting98466
+Node: Filename Expansion100410
+Node: Pattern Matching103010
+Node: Quote Removal107618
+Node: Redirections107913
+Node: Executing Commands117573
+Node: Simple Command Expansion118243
+Node: Command Search and Execution120353
+Node: Command Execution Environment122731
+Node: Environment125766
+Node: Exit Status127429
+Node: Signals129213
+Node: Shell Scripts131180
+Node: Shell Builtin Commands134207
+Node: Bourne Shell Builtins136245
+Node: Bash Builtins157706
+Node: Modifying Shell Behavior188523
+Node: The Set Builtin188868
+Node: The Shopt Builtin199281
+Node: Special Builtins214710
+Node: Shell Variables215689
+Node: Bourne Shell Variables216126
+Node: Bash Variables218230
+Node: Bash Features251045
+Node: Invoking Bash252058
+Node: Bash Startup Files258071
+Node: Interactive Shells263174
+Node: What is an Interactive Shell?263584
+Node: Is this Shell Interactive?264233
+Node: Interactive Shell Behavior265048
+Node: Bash Conditional Expressions268561
+Node: Shell Arithmetic273203
+Node: Aliases276147
+Node: Arrays278760
+Node: The Directory Stack284769
+Node: Directory Stack Builtins285553
+Node: Controlling the Prompt289813
+Node: The Restricted Shell292778
+Node: Bash POSIX Mode295375
+Node: Shell Compatibility Mode306648
+Node: Job Control313304
+Node: Job Control Basics313764
+Node: Job Control Builtins318766
+Node: Job Control Variables324166
+Node: Command Line Editing325322
+Node: Introduction and Notation326993
+Node: Readline Interaction328616
+Node: Readline Bare Essentials329807
+Node: Readline Movement Commands331590
+Node: Readline Killing Commands332550
+Node: Readline Arguments334468
+Node: Searching335512
+Node: Readline Init File337698
+Node: Readline Init File Syntax338959
+Node: Conditional Init Constructs360239
+Node: Sample Init File364435
+Node: Bindable Readline Commands367559
+Node: Commands For Moving368763
+Node: Commands For History370814
+Node: Commands For Text375808
+Node: Commands For Killing379457
+Node: Numeric Arguments382490
+Node: Commands For Completion383629
+Node: Keyboard Macros387820
+Node: Miscellaneous Commands388507
+Node: Readline vi Mode394446
+Node: Programmable Completion395353
+Node: Programmable Completion Builtins403133
+Node: A Programmable Completion Example413828
+Node: Using History Interactively419075
+Node: Bash History Facilities419759
+Node: Bash History Builtins422764
+Node: History Interaction427772
+Node: Event Designators431392
+Node: Word Designators432746
+Node: Modifiers434506
+Node: Installing Bash436317
+Node: Basic Installation437454
+Node: Compilers and Options441176
+Node: Compiling For Multiple Architectures441917
+Node: Installation Names443610
+Node: Specifying the System Type445719
+Node: Sharing Defaults446435
+Node: Operation Controls447108
+Node: Optional Features448066
+Node: Reporting Bugs459159
+Node: Major Differences From The Bourne Shell460434
+Node: GNU Free Documentation License477284
+Node: Indexes502461
+Node: Builtin Index502915
+Node: Reserved Word Index509742
+Node: Variable Index512190
+Node: Function Index528682
+Node: Concept Index542466
 
 End Tag Table