asort/asorti documentation update and new lint warning.

7 files changed, 490 insertions, 440 deletions

diff --git a/ChangeLog b/ChangeLog
index 4b1484f0..2d899819 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2021-07-07         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* array.c (asort_actual): Add a lint warning for passing the
+	same array as the first two arguments without a third.
+	Thanks to Peng Yu <pengyu.ut@gmail.com> for the report.
+
 2021-06-30         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* custom.h: Add a bunch of defines to work around the continous,
diff --git a/array.c b/array.c
index 50efddb2..76853779 100644
--- a/array.c
+++ b/array.c
@@ -802,6 +802,7 @@ asort_actual(int nargs, sort_context_t ctxt)
 	unsigned long num_elems, i;
 	const char *sort_str;
 	char save;
+	const char *name = (ctxt == ASORT ? "asort" : "asorti");	// D.R.Y.
 
 	if (nargs == 3)  /* 3rd optional arg */
 		s = POP_STRING();
@@ -822,36 +823,38 @@ asort_actual(int nargs, sort_context_t ctxt)
 	if (nargs >= 2) {  /* 2nd optional arg */
 		dest = POP_PARAM();
 		if (dest->type != Node_var_array) {
-			fatal(_("%s: second argument is not an array"),
-				ctxt == ASORT ? "asort" : "asorti");
+			fatal(_("%s: second argument is not an array"), name);
 		}
-		check_symtab_functab(dest,
-				ctxt == ASORT ? "asort" : "asorti",
+		check_symtab_functab(dest, name,
 				_("%s: cannot use %s as second argument"));
 	}
 
 	array = POP_PARAM();
 	if (array->type != Node_var_array) {
-		fatal(_("%s: first argument is not an array"),
-			ctxt == ASORT ? "asort" : "asorti");
+		fatal(_("%s: first argument is not an array"), name);
 	}
 	else if (array == symbol_table && dest == NULL)
-		fatal(_("%s: first argument cannot be SYMTAB without a second argument"),
-			ctxt == ASORT ? "asort" : "asorti");
+		fatal(_("%s: first argument cannot be SYMTAB without a second argument"), name);
 	else if (array == func_table && dest == NULL)
-		fatal(_("%s: first argument cannot be FUNCTAB without a second argument"),
-			ctxt == ASORT ? "asort" : "asorti");
+		fatal(_("%s: first argument cannot be FUNCTAB without a second argument"), name);
 
 	if (dest != NULL) {
+		static bool warned = false;
+
+		if (nargs == 2 && array == dest && ! warned) {
+			warned = true;
+			lintwarn(_("asort/asorti: using the same array as source and destination without "
+				   "a third argument is silly."));
+		}
 		for (r = dest->parent_array; r != NULL; r = r->parent_array) {
 			if (r == array)
 				fatal(_("%s: cannot use a subarray of first argument for second argument"),
-					ctxt == ASORT ? "asort" : "asorti");
+					name);
 		}
 		for (r = array->parent_array; r != NULL; r = r->parent_array) {
 			if (r == dest)
 				fatal(_("%s: cannot use a subarray of second argument for first argument"),
-					ctxt == ASORT ? "asort" : "asorti");
+					name);
 		}
 	}
 
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 488f01b2..c087e58e 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2021-07-05         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawk.1: Document that asort() and asorti() allow the same array to
+	be passed for the first and second arguments.
+	* gawktexi.in (String Functions, Array Sorting Functions): Ditto.
+	Thanks to Peng Yu <pengyu.ut@gmail.com> for the report.
+
 2021-07-02         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in (Bugs): Added discussion of what is and is not
diff --git a/doc/gawk.1 b/doc/gawk.1
index a8cf39f6..0d498ab1 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -13,7 +13,7 @@
 .		if \w'\(rq' .ds rq "\(rq
 .	\}
 .\}
-.TH GAWK 1 "Aug 31 2020" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Jul 05 2021" "Free Software Foundation" "Utility Commands"
 .SH NAME
 gawk \- pattern scanning and processing language
 .SH SYNOPSIS
@@ -2940,6 +2940,9 @@ any of the strings valid for
 It can also be the name of a user-defined
 comparison function as described in
 \fBPROCINFO["sorted_in"]\fR.
+.IR s " and " d
+are allowed to be the same array; this only makes sense when
+supplying the third argument as well.
 .TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n"
 \fBasorti(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
 Return the number of elements in the source
@@ -2959,6 +2962,10 @@ The purpose of the optional string
 is the same as described
 previously for
 .BR asort() .
+Here too,
+.IR s " and " d
+are allowed to be the same array; this only makes sense when
+supplying the third argument as well.
 .TP
 \fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR
 Search the target string
@@ -4265,7 +4272,7 @@ We thank him.
 .SH COPYING PERMISSIONS
 Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996,
 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009,
-2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020,
+2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021,
 Free Software Foundation, Inc.
 .PP
 Permission is granted to make and distribute verbatim copies of
diff --git a/doc/gawk.info b/doc/gawk.info
index 95ddb3ab..d5a0d604 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -13057,6 +13057,10 @@ Options::):
           argument, but only if providing a second array to use for the
           actual sorting.
 
+     You are allowed to use the same array for both the SOURCE and DEST
+     arguments, but doing so only makes sense if you're also supplying
+     the third argument.
+
 'gensub(REGEXP, REPLACEMENT, HOW' [', TARGET']') #'
      Search the target string TARGET for matches of the regular
      expression REGEXP.  If HOW is a string beginning with 'g' or 'G'
@@ -21306,6 +21310,11 @@ result array.
      second one, there is only one copy of the original array elements'
      data, even though both arrays use the values.
 
+   You may use the same array for both the first and second arguments to
+'asort()' and 'asorti()'.  Doing so only makes sense if you are also
+supplying the third argument, since 'awk' doesn't provide a way to pass
+that third argument without also passing the first and second ones.
+
    Because 'IGNORECASE' affects string comparisons, the value of
 'IGNORECASE' also affects sorting for both 'asort()' and 'asorti()'.
 Note also that the locale's sorting order does _not_ come into play;
@@ -34928,7 +34937,7 @@ Index
 * * (asterisk), *= operator <1>:         Precedence.          (line  94)
 * * (asterisk), **= operator <1>:        Precedence.          (line  94)
 * * (asterisk), * operator, null strings, matching: String Functions.
-                                                              (line 548)
+                                                              (line 552)
 * + (plus sign), regexp operator:        Regexp Operator Details.
                                                               (line 107)
 * + (plus sign), += operator:            Assignment Ops.      (line  81)
@@ -35310,7 +35319,7 @@ Index
 * arrays, multidimensional, scanning:    Multiscanning.       (line  11)
 * arrays, arrays of arrays:              Arrays of Arrays.    (line   6)
 * arrays, elements, retrieving number of: String Functions.   (line  42)
-* arrays, number of elements:            String Functions.    (line 207)
+* arrays, number of elements:            String Functions.    (line 211)
 * arrays, as parameters to functions:    Pass By Value/Reference.
                                                               (line  44)
 * arrays, associative, library functions and: Library Names.  (line  58)
@@ -35320,7 +35329,7 @@ Index
 * arrays, sorting, asorti() function (gawk): Array Sorting Functions.
                                                               (line   6)
 * arrays, sorting, IGNORECASE variable and: Array Sorting Functions.
-                                                              (line  83)
+                                                              (line  88)
 * artificial intelligence, gawk and:     Distribution contents.
                                                               (line  58)
 * ASCII:                                 Escape Sequences.    (line  31)
@@ -35369,7 +35378,7 @@ Index
 * asterisk (*), *= operator <1>:         Precedence.          (line  94)
 * asterisk (*), **= operator <1>:        Precedence.          (line  94)
 * asterisk (*), * operator, null strings, matching: String Functions.
-                                                              (line 548)
+                                                              (line 552)
 * at-sign (@), @include directive:       Include Files.       (line   8)
 * at-sign (@), @load directive:          Loading Shared Libraries.
                                                               (line   8)
@@ -35614,7 +35623,7 @@ Index
 * Brian Kernighan's awk <9>:             Continue Statement.  (line  44)
 * Brian Kernighan's awk <10>:            Nextfile Statement.  (line  47)
 * Brian Kernighan's awk <11>:            Delete.              (line  51)
-* Brian Kernighan's awk <12>:            String Functions.    (line 504)
+* Brian Kernighan's awk <12>:            String Functions.    (line 508)
 * Brian Kernighan's awk <13>:            Gory Details.        (line  19)
 * Brian Kernighan's awk <14>:            I/O Functions.       (line  43)
 * Brian Kernighan's awk, extensions:     BTL.                 (line   6)
@@ -35678,7 +35687,7 @@ Index
 * case sensitivity, string comparisons and: User-modified.    (line  79)
 * case sensitivity, regexps and <1>:     User-modified.       (line  79)
 * case sensitivity, array indices and:   Array Intro.         (line 100)
-* case sensitivity, converting case:     String Functions.    (line 534)
+* case sensitivity, converting case:     String Functions.    (line 538)
 * case sensitivity, example programs:    Library Functions.   (line  53)
 * CGI, awk scripts for:                  Options.             (line 147)
 * character sets (machine character encodings): Ordinal Functions.
@@ -35762,7 +35771,7 @@ Index
 * common extensions, **= operator:       Assignment Ops.      (line 138)
 * common extensions, delete to delete entire arrays: Delete.  (line  39)
 * common extensions, length() applied to an array: String Functions.
-                                                              (line 207)
+                                                              (line 211)
 * common extensions, func keyword:       Definition Syntax.   (line  99)
 * common extensions, BINMODE variable:   PC Using.            (line  20)
 * comp.lang.awk newsgroup:               Usenet.              (line  11)
@@ -35820,9 +35829,9 @@ Index
 * converting, numbers to strings:        Strings And Numbers. (line   6)
 * converting, integer array subscripts to strings: Numeric Array Subscripts.
                                                               (line  31)
-* converting, string to numbers <1>:     String Functions.    (line 402)
-* converting, string to lower case:      String Functions.    (line 535)
-* converting, string to upper case:      String Functions.    (line 541)
+* converting, string to numbers <1>:     String Functions.    (line 406)
+* converting, string to lower case:      String Functions.    (line 539)
+* converting, string to upper case:      String Functions.    (line 545)
 * converting, dates to timestamps:       Time Functions.      (line  78)
 * converting, string to numbers <2>:     Bitwise Functions.   (line 109)
 * converting, numbers to strings <1>:    Bitwise Functions.   (line 109)
@@ -35910,9 +35919,9 @@ Index
 * dark corner, array subscripts:         Uninitialized Subscripts.
                                                               (line  43)
 * dark corner, regexp as second argument to index(): String Functions.
-                                                              (line 171)
-* dark corner, length() function:        String Functions.    (line 193)
-* dark corner, split() function:         String Functions.    (line 372)
+                                                              (line 175)
+* dark corner, length() function:        String Functions.    (line 197)
+* dark corner, split() function:         String Functions.    (line 376)
 * dark corner, parameter name restrictions: Definition Syntax.
                                                               (line  44)
 * dark corner <1>:                       Glossary.            (line 266)
@@ -36162,11 +36171,11 @@ Index
 * differences in awk and gawk, function arguments: Calling Built-in.
                                                               (line  16)
 * differences in awk and gawk, length() function: String Functions.
-                                                              (line 207)
+                                                              (line 211)
 * differences in awk and gawk, match() function: String Functions.
-                                                              (line 269)
+                                                              (line 273)
 * differences in awk and gawk, split() function: String Functions.
-                                                              (line 357)
+                                                              (line 361)
 * differences in awk and gawk, indirect function calls: Indirect Calls.
                                                               (line   6)
 * differences in awk and gawk, BINMODE variable <1>: PC Using.
@@ -36365,7 +36374,7 @@ Index
 * extensions, common, **= operator:      Assignment Ops.      (line 138)
 * extensions, common, delete to delete entire arrays: Delete. (line  39)
 * extensions, common, length() applied to an array: String Functions.
-                                                              (line 207)
+                                                              (line 211)
 * extensions, common, fflush() function: I/O Functions.       (line  43)
 * extensions, common, func keyword:      Definition Syntax.   (line  99)
 * extensions, loadable, allocating memory: Memory Allocation Functions.
@@ -36497,7 +36506,7 @@ Index
                                                               (line  80)
 * files, message object, converting from portable object files: I18N Example.
                                                               (line  80)
-* find substring in string:              String Functions.    (line 162)
+* find substring in string:              String Functions.    (line 166)
 * finding extensions:                    Finding Extensions.  (line   6)
 * finish debugger command:               Debugger Execution Control.
                                                               (line  39)
@@ -36534,7 +36543,7 @@ Index
 * format time string:                    Time Functions.      (line  50)
 * formats, numeric output:               OFMT.                (line   6)
 * formatting, output:                    Printf.              (line   6)
-* formatting, strings:                   String Functions.    (line 395)
+* formatting, strings:                   String Functions.    (line 399)
 * forward slash (/), to enclose regular expressions: Regexp.  (line  10)
 * forward slash (/), /= operator:        Assignment Ops.      (line 129)
 * forward slash (/), /= operator, vs. /=.../ regexp constant: Assignment Ops.
@@ -36696,7 +36705,7 @@ Index
 * gawk, string-translation functions:    I18N Functions.      (line   6)
 * gawk, features, advanced:              Advanced Features.   (line   6)
 * gawk, IGNORECASE variable in <4>:      Array Sorting Functions.
-                                                              (line  83)
+                                                              (line  88)
 * gawk, PROCINFO array in <3>:           Two-way I/O.         (line 114)
 * gawk, ERRNO variable in <4>:           TCP/IP Networking.   (line  54)
 * gawk, dynamic profiling:               Profiling.           (line 185)
@@ -36736,7 +36745,7 @@ Index
 * generate time values:                  Time Functions.      (line  25)
 * gensub:                                Standard Regexp Constants.
                                                               (line  43)
-* gensub <1>:                            String Functions.    (line  95)
+* gensub <1>:                            String Functions.    (line  99)
 * gensub() function (gawk), escape processing: Gory Details.  (line   6)
 * getaddrinfo() function (C library):    TCP/IP Networking.   (line  39)
 * getgrent() function (C library):       Group Functions.     (line   6)
@@ -36820,8 +36829,8 @@ Index
 * groups, information about:             Group Functions.     (line   6)
 * gsub:                                  Standard Regexp Constants.
                                                               (line  43)
-* gsub <1>:                              String Functions.    (line 146)
-* gsub() function, arguments of:         String Functions.    (line 474)
+* gsub <1>:                              String Functions.    (line 150)
+* gsub() function, arguments of:         String Functions.    (line 478)
 * gsub() function, escape processing:    Gory Details.        (line   6)
 * Guerrero, Juan Manuel:                 Acknowledgments.     (line  60)
 * Guerrero, Juan Manuel <1>:             Contributors.        (line 150)
@@ -36867,7 +36876,7 @@ Index
 * IGNORECASE variable, in example programs: Library Functions.
                                                               (line  53)
 * IGNORECASE variable, array sorting functions and: Array Sorting Functions.
-                                                              (line  83)
+                                                              (line  88)
 * Illumos, POSIX-compliant awk:          Other Versions.      (line 109)
 * implementation issues, gawk, limits:   Getline Notes.       (line  14)
 * implementation issues, gawk, limits <1>: Redirection.       (line 129)
@@ -36888,7 +36897,7 @@ Index
 * @include directive:                    Include Files.       (line   8)
 * including files, @include directive:   Include Files.       (line   8)
 * increment operators:                   Increment Ops.       (line   6)
-* index:                                 String Functions.    (line 162)
+* index:                                 String Functions.    (line 166)
 * indexing arrays:                       Array Intro.         (line  48)
 * indirect function calls:               Indirect Calls.      (line   6)
 * indirect function calls, @-notation:   Indirect Calls.      (line  47)
@@ -36914,7 +36923,7 @@ Index
                                                               (line   6)
 * input files, counting elements in:     Wc Program.          (line   6)
 * input pipeline:                        Getline/Pipe.        (line  10)
-* input record, length of:               String Functions.    (line 184)
+* input record, length of:               String Functions.    (line 188)
 * input redirection:                     Getline/File.        (line   6)
 * input/output, from BEGIN and END:      I/O And BEGIN/END.   (line   6)
 * input/output, binary:                  User-modified.       (line  15)
@@ -37026,9 +37035,9 @@ Index
 * left angle bracket (<), <= operator <1>: Precedence.        (line  64)
 * left shift, bitwise:                   Bitwise Functions.   (line  32)
 * leftmost longest match:                Multiple Line.       (line  26)
-* length:                                String Functions.    (line 177)
-* length of input record:                String Functions.    (line 184)
-* length of string:                      String Functions.    (line 177)
+* length:                                String Functions.    (line 181)
+* length of input record:                String Functions.    (line 188)
+* length of string:                      String Functions.    (line 181)
 * Lesser General Public License (LGPL):  Glossary.            (line 489)
 * LGPL (Lesser General Public License):  Glossary.            (line 489)
 * libmawk:                               Other Versions.      (line 146)
@@ -37118,15 +37127,15 @@ Index
 * marked string extraction (internationalization): String Extraction.
                                                               (line   6)
 * Marx, Groucho:                         Increment Ops.       (line  60)
-* match:                                 String Functions.    (line 217)
-* match regexp in string:                String Functions.    (line 217)
+* match:                                 String Functions.    (line 221)
+* match regexp in string:                String Functions.    (line 221)
 * match() function, RSTART/RLENGTH variables: String Functions.
-                                                              (line 234)
-* match() function, side effects:        String Functions.    (line 234)
+                                                              (line 238)
+* match() function, side effects:        String Functions.    (line 238)
 * matching, leftmost longest:            Multiple Line.       (line  26)
 * matching, expressions:                 Typing and Comparison.
                                                               (line   9)
-* matching, null strings:                String Functions.    (line 548)
+* matching, null strings:                String Functions.    (line 552)
 * mawk utility:                          Escape Sequences.    (line 121)
 * mawk utility <1>:                      Getline/Pipe.        (line  62)
 * mawk utility <2>:                      Concatenation.       (line  36)
@@ -37255,9 +37264,9 @@ Index
 * null strings, as array subscripts:     Uninitialized Subscripts.
                                                               (line  43)
 * null strings, deleting array elements and: Delete.          (line  27)
-* null strings, matching:                String Functions.    (line 548)
+* null strings, matching:                String Functions.    (line 552)
 * null strings <3>:                      Basic Data Typing.   (line  26)
-* number of array elements:              String Functions.    (line 207)
+* number of array elements:              String Functions.    (line 211)
 * number sign (#), #! (executable scripts): Executable Scripts.
                                                               (line   6)
 * number sign (#), commenting:           Comments.            (line   6)
@@ -37366,7 +37375,7 @@ Index
                                                               (line  77)
 * parentheses (), in a profile:          Profiling.           (line 146)
 * password file:                         Passwd Functions.    (line  16)
-* patsplit:                              String Functions.    (line 303)
+* patsplit:                              String Functions.    (line 307)
 * patterns, default:                     Very Simple.         (line  35)
 * patterns, regexp constants as:         Regexp Usage.        (line   6)
 * patterns:                              Patterns and Actions.
@@ -37429,8 +37438,8 @@ Index
 * portability, operators:                Increment Ops.       (line  60)
 * portability, operators, not in POSIX awk: Precedence.       (line  97)
 * portability, deleting array elements:  Delete.              (line  56)
-* portability, length() function:        String Functions.    (line 186)
-* portability, substr() function:        String Functions.    (line 524)
+* portability, length() function:        String Functions.    (line 190)
+* portability, substr() function:        String Functions.    (line 528)
 * portability, functions, defining:      Definition Syntax.   (line 114)
 * portability, next statement in user-defined functions: Function Caveats.
                                                               (line  26)
@@ -37484,7 +37493,7 @@ Index
 * POSIX awk, continue statement and:     Continue Statement.  (line  44)
 * POSIX awk, next/nextfile statements and: Next Statement.    (line  44)
 * POSIX awk, CONVFMT variable and:       User-modified.       (line  30)
-* POSIX awk, functions and, length():    String Functions.    (line 186)
+* POSIX awk, functions and, length():    String Functions.    (line 190)
 * POSIX awk, functions and, gsub()/sub(): Gory Details.       (line  90)
 * POSIX awk, timestamps and:             Time Functions.      (line   6)
 * POSIX awk, date utility and:           Time Functions.      (line 255)
@@ -37505,7 +37514,7 @@ Index
                                                               (line  12)
 * POSIX mode <9>:                        POSIX String Comparison.
                                                               (line  34)
-* POSIX mode <10>:                       String Functions.    (line 391)
+* POSIX mode <10>:                       String Functions.    (line 395)
 * POSIX mode <11>:                       Controlling Array Traversal.
                                                               (line 226)
 * POSIX mode <12>:                       POSIX Floating Point Problems.
@@ -37723,7 +37732,7 @@ Index
 * regular expressions, as patterns <1>:  Regexp Patterns.     (line   6)
 * regular expressions, case sensitivity <1>: User-modified.   (line  79)
 * regular expressions, searching for:    Egrep Program.       (line   6)
-* replace in string:                     String Functions.    (line 420)
+* replace in string:                     String Functions.    (line 424)
 * retrying input:                        Retrying Input.      (line   6)
 * return debugger command:               Debugger Execution Control.
                                                               (line  54)
@@ -37748,7 +37757,7 @@ Index
 * right shift, bitwise:                  Bitwise Functions.   (line  32)
 * Ritchie, Dennis:                       Basic Data Typing.   (line  54)
 * RLENGTH variable:                      Auto-set.            (line 335)
-* RLENGTH variable, match() function and: String Functions.   (line 234)
+* RLENGTH variable, match() function and: String Functions.   (line 238)
 * Robbins, Miriam:                       Acknowledgments.     (line  94)
 * Robbins, Jean:                         Acknowledgments.     (line  94)
 * Robbins, Harry:                        Acknowledgments.     (line  94)
@@ -37778,7 +37787,7 @@ Index
 * RS variable <1>:                       User-modified.       (line 136)
 * rshift:                                Bitwise Functions.   (line  54)
 * RSTART variable:                       Auto-set.            (line 341)
-* RSTART variable, match() function and: String Functions.    (line 234)
+* RSTART variable, match() function and: String Functions.    (line 238)
 * RT variable:                           awk split records.   (line 118)
 * RT variable <1>:                       gawk split records.  (line  66)
 * RT variable <2>:                       Multiple Line.       (line 139)
@@ -37804,8 +37813,8 @@ Index
 * Schorr, Andrew <2>:                    Contributors.        (line 136)
 * Schreiber, Bert:                       Acknowledgments.     (line  38)
 * Schreiber, Rita:                       Acknowledgments.     (line  38)
-* search and replace in strings:         String Functions.    (line  95)
-* search for substring:                  String Functions.    (line 162)
+* search and replace in strings:         String Functions.    (line  99)
+* search for substring:                  String Functions.    (line 166)
 * search paths, for source files:        AWKPATH Variable.    (line   6)
 * search paths, for loadable extensions: AWKLIBPATH Variable. (line   6)
 * search paths:                          Programs Exercises.  (line  70)
@@ -37887,9 +37896,9 @@ Index
 * side effects, statements:              Action Overview.     (line  32)
 * side effects, array indexing:          Reference to Elements.
                                                               (line  43)
-* side effects, match() function:        String Functions.    (line 234)
-* side effects, sub() function:          String Functions.    (line 474)
-* side effects, gsub() function:         String Functions.    (line 474)
+* side effects, match() function:        String Functions.    (line 238)
+* side effects, sub() function:          String Functions.    (line 478)
+* side effects, gsub() function:         String Functions.    (line 478)
 * side effects, asort() function:        Array Sorting Functions.
                                                               (line  24)
 * side effects, asorti() function:       Array Sorting Functions.
@@ -37925,7 +37934,7 @@ Index
                                                               (line 147)
 * sidebar, Operator Evaluation Order:    Increment Ops.       (line  58)
 * sidebar, Changing NR and FNR:          Auto-set.            (line 407)
-* sidebar, Matching the Null String:     String Functions.    (line 546)
+* sidebar, Matching the Null String:     String Functions.    (line 550)
 * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions.
                                                               (line  74)
 * sidebar, Controlling Output Buffering with system(): I/O Functions.
@@ -37995,13 +38004,13 @@ Index
 * source files, search path for:         Programs Exercises.  (line  70)
 * sparse arrays:                         Array Intro.         (line  76)
 * Spencer, Henry:                        Glossary.            (line  16)
-* split:                                 String Functions.    (line 324)
-* split string into array:               String Functions.    (line 303)
+* split:                                 String Functions.    (line 328)
+* split string into array:               String Functions.    (line 307)
 * split utility:                         Split Program.       (line   6)
 * split() function, array elements, deleting: Delete.         (line  61)
 * split.awk program:                     Split Program.       (line  51)
 * sprintf:                               OFMT.                (line  15)
-* sprintf <1>:                           String Functions.    (line 395)
+* sprintf <1>:                           String Functions.    (line 399)
 * sprintf() function, print/printf statements and: Round Function.
                                                               (line   6)
 * sqrt:                                  Numeric Functions.   (line  78)
@@ -38036,8 +38045,8 @@ Index
 * string, constants, vs. regexp constants: Computed Regexps.  (line  40)
 * string, constants:                     Scalar Constants.    (line  15)
 * string, operators:                     Concatenation.       (line   9)
-* string, length:                        String Functions.    (line 177)
-* string, regular expression match of:   String Functions.    (line 217)
+* string, length:                        String Functions.    (line 181)
+* string, regular expression match of:   String Functions.    (line 221)
 * string, extraction (internationalization): String Extraction.
                                                               (line   6)
 * string-manipulation functions:         String Functions.    (line   6)
@@ -38052,19 +38061,19 @@ Index
 * strings, numeric:                      Variable Typing.     (line  67)
 * strings, converting, numbers to:       User-modified.       (line  30)
 * strings, converting, numbers to <1>:   User-modified.       (line 107)
-* strings, splitting, example:           String Functions.    (line 343)
-* strings, converting letter case:       String Functions.    (line 534)
+* strings, splitting, example:           String Functions.    (line 347)
+* strings, converting letter case:       String Functions.    (line 538)
 * strings, converting <1>:               Bitwise Functions.   (line 109)
 * strings, merging arrays into:          Join Function.       (line   6)
 * strings, for localization:             Programmer i18n.     (line  13)
 * strings, extracting:                   String Extraction.   (line   6)
-* strtonum:                              String Functions.    (line 402)
+* strtonum:                              String Functions.    (line 406)
 * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data.
                                                               (line  35)
 * sub:                                   Standard Regexp Constants.
                                                               (line  43)
-* sub <1>:                               String Functions.    (line 420)
-* sub() function, arguments of:          String Functions.    (line 474)
+* sub <1>:                               String Functions.    (line 424)
+* sub() function, arguments of:          String Functions.    (line 478)
 * sub() function, escape processing:     Gory Details.        (line   6)
 * subscript separators:                  User-modified.       (line 149)
 * subscripts in arrays, numbers as:      Numeric Array Subscripts.
@@ -38077,9 +38086,9 @@ Index
 * SUBSEP variable:                       User-modified.       (line 149)
 * SUBSEP variable, multidimensional arrays and: Multidimensional.
                                                               (line  16)
-* substitute in string:                  String Functions.    (line  95)
-* substr:                                String Functions.    (line 493)
-* substring:                             String Functions.    (line 493)
+* substitute in string:                  String Functions.    (line  99)
+* substr:                                String Functions.    (line 497)
+* substring:                             String Functions.    (line 497)
 * Sumner, Andrew:                        Other Versions.      (line  64)
 * supplementary groups of gawk process:  Auto-set.            (line 292)
 * switch statement:                      Switch Statement.    (line   6)
@@ -38140,8 +38149,8 @@ Index
 * timestamps, converting dates to:       Time Functions.      (line  78)
 * timestamps, formatted:                 Getlocaltime Function.
                                                               (line   6)
-* tolower:                               String Functions.    (line 535)
-* toupper:                               String Functions.    (line 541)
+* tolower:                               String Functions.    (line 539)
+* toupper:                               String Functions.    (line 545)
 * tr utility:                            Translate Program.   (line   6)
 * trace debugger command:                Miscellaneous Debugger Commands.
                                                               (line 108)
@@ -38173,9 +38182,9 @@ Index
 * troubleshooting, function call syntax: Function Calls.      (line  30)
 * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in.
                                                               (line  16)
-* troubleshooting, match() function:     String Functions.    (line 298)
-* troubleshooting, gsub()/sub() functions: String Functions.  (line 484)
-* troubleshooting, substr() function:    String Functions.    (line 511)
+* troubleshooting, match() function:     String Functions.    (line 302)
+* troubleshooting, gsub()/sub() functions: String Functions.  (line 488)
+* troubleshooting, substr() function:    String Functions.    (line 515)
 * troubleshooting, fflush() function:    I/O Functions.       (line  63)
 * troubleshooting, system() function:    I/O Functions.       (line 128)
 * troubleshooting, readable data files:  File Checking.       (line   6)
@@ -38620,362 +38629,362 @@ Ref: Numeric Functions-Footnote-1548889
 Ref: Numeric Functions-Footnote-2549537
 Ref: Numeric Functions-Footnote-3549585
 Node: String Functions549857
-Ref: String Functions-Footnote-1573998
-Ref: String Functions-Footnote-2574126
-Ref: String Functions-Footnote-3574374
-Node: Gory Details574461
-Ref: table-sub-escapes576252
-Ref: table-sub-proposed577771
-Ref: table-posix-sub579134
-Ref: table-gensub-escapes580675
-Ref: Gory Details-Footnote-1581498
-Node: I/O Functions581652
-Ref: table-system-return-values588106
-Ref: I/O Functions-Footnote-1590186
-Ref: I/O Functions-Footnote-2590334
-Node: Time Functions590454
-Ref: Time Functions-Footnote-1601125
-Ref: Time Functions-Footnote-2601193
-Ref: Time Functions-Footnote-3601351
-Ref: Time Functions-Footnote-4601462
-Ref: Time Functions-Footnote-5601574
-Ref: Time Functions-Footnote-6601801
-Node: Bitwise Functions602067
-Ref: table-bitwise-ops602661
-Ref: Bitwise Functions-Footnote-1608724
-Ref: Bitwise Functions-Footnote-2608897
-Node: Type Functions609088
-Node: I18N Functions611951
-Node: User-defined613602
-Node: Definition Syntax614414
-Ref: Definition Syntax-Footnote-1620108
-Node: Function Example620179
-Ref: Function Example-Footnote-1623101
-Node: Function Calling623123
-Node: Calling A Function623711
-Node: Variable Scope624669
-Node: Pass By Value/Reference627663
-Node: Function Caveats630307
-Ref: Function Caveats-Footnote-1632354
-Node: Return Statement632474
-Node: Dynamic Typing635453
-Node: Indirect Calls636383
-Ref: Indirect Calls-Footnote-1646635
-Node: Functions Summary646763
-Node: Library Functions649468
-Ref: Library Functions-Footnote-1653075
-Ref: Library Functions-Footnote-2653218
-Node: Library Names653389
-Ref: Library Names-Footnote-1657056
-Ref: Library Names-Footnote-2657279
-Node: General Functions657365
-Node: Strtonum Function658547
-Node: Assert Function661569
-Node: Round Function664895
-Node: Cliff Random Function666435
-Node: Ordinal Functions667451
-Ref: Ordinal Functions-Footnote-1670514
-Ref: Ordinal Functions-Footnote-2670766
-Node: Join Function670976
-Ref: Join Function-Footnote-1672746
-Node: Getlocaltime Function672946
-Node: Readfile Function676688
-Node: Shell Quoting678665
-Node: Isnumeric Function680093
-Node: Data File Management681430
-Node: Filetrans Function682062
-Node: Rewind Function686158
-Node: File Checking688067
-Ref: File Checking-Footnote-1689401
-Node: Empty Files689602
-Node: Ignoring Assigns691581
-Node: Getopt Function693131
-Ref: Getopt Function-Footnote-1708354
-Node: Passwd Functions708554
-Ref: Passwd Functions-Footnote-1717393
-Node: Group Functions717481
-Ref: Group Functions-Footnote-1725379
-Node: Walking Arrays725586
-Node: Library Functions Summary728594
-Node: Library Exercises730000
-Node: Sample Programs730465
-Node: Running Examples731235
-Node: Clones731963
-Node: Cut Program733187
-Node: Egrep Program743327
-Node: Id Program752328
-Node: Split Program762275
-Ref: Split Program-Footnote-1772168
-Node: Tee Program772341
-Node: Uniq Program775131
-Node: Wc Program782719
-Node: Bytes vs. Characters783106
-Node: Using extensions784654
-Node: wc program785408
-Node: Miscellaneous Programs790273
-Node: Dupword Program791486
-Node: Alarm Program793516
-Node: Translate Program798371
-Ref: Translate Program-Footnote-1802936
-Node: Labels Program803206
-Ref: Labels Program-Footnote-1806557
-Node: Word Sorting806641
-Node: History Sorting810713
-Node: Extract Program812938
-Node: Simple Sed820992
-Node: Igawk Program824066
-Ref: Igawk Program-Footnote-1838397
-Ref: Igawk Program-Footnote-2838599
-Ref: Igawk Program-Footnote-3838721
-Node: Anagram Program838836
-Node: Signature Program841898
-Node: Programs Summary843145
-Node: Programs Exercises844359
-Ref: Programs Exercises-Footnote-1848489
-Node: Advanced Features848575
-Node: Nondecimal Data850642
-Node: Array Sorting852233
-Node: Controlling Array Traversal852933
-Ref: Controlling Array Traversal-Footnote-1861301
-Node: Array Sorting Functions861419
-Ref: Array Sorting Functions-Footnote-1866510
-Node: Two-way I/O866706
-Ref: Two-way I/O-Footnote-1874432
-Ref: Two-way I/O-Footnote-2874619
-Node: TCP/IP Networking874701
-Node: Profiling877819
-Node: Extension Philosophy887128
-Node: Advanced Features Summary888607
-Node: Internationalization890622
-Node: I18N and L10N892296
-Node: Explaining gettext892983
-Ref: Explaining gettext-Footnote-1898875
-Ref: Explaining gettext-Footnote-2899060
-Node: Programmer i18n899225
-Ref: Programmer i18n-Footnote-1904174
-Node: Translator i18n904223
-Node: String Extraction905017
-Ref: String Extraction-Footnote-1906149
-Node: Printf Ordering906235
-Ref: Printf Ordering-Footnote-1909021
-Node: I18N Portability909085
-Ref: I18N Portability-Footnote-1911541
-Node: I18N Example911604
-Ref: I18N Example-Footnote-1914879
-Ref: I18N Example-Footnote-2914952
-Node: Gawk I18N915061
-Node: I18N Summary915710
-Node: Debugger917051
-Node: Debugging918051
-Node: Debugging Concepts918492
-Node: Debugging Terms920301
-Node: Awk Debugging922876
-Ref: Awk Debugging-Footnote-1923821
-Node: Sample Debugging Session923953
-Node: Debugger Invocation924487
-Node: Finding The Bug925873
-Node: List of Debugger Commands932347
-Node: Breakpoint Control933680
-Node: Debugger Execution Control937374
-Node: Viewing And Changing Data940736
-Node: Execution Stack944277
-Node: Debugger Info945914
-Node: Miscellaneous Debugger Commands949985
-Node: Readline Support955047
-Node: Limitations955943
-Node: Debugging Summary958497
-Node: Namespaces959776
-Node: Global Namespace960887
-Node: Qualified Names962285
-Node: Default Namespace963284
-Node: Changing The Namespace964025
-Node: Naming Rules965639
-Node: Internal Name Management967487
-Node: Namespace Example968529
-Node: Namespace And Features971091
-Node: Namespace Summary972526
-Node: Arbitrary Precision Arithmetic974003
-Node: Computer Arithmetic975490
-Ref: table-numeric-ranges979256
-Ref: table-floating-point-ranges979749
-Ref: Computer Arithmetic-Footnote-1980407
-Node: Math Definitions980464
-Ref: table-ieee-formats983780
-Ref: Math Definitions-Footnote-1984383
-Node: MPFR features984488
-Node: FP Math Caution986206
-Ref: FP Math Caution-Footnote-1987278
-Node: Inexactness of computations987647
-Node: Inexact representation988607
-Node: Comparing FP Values989967
-Node: Errors accumulate991208
-Node: Getting Accuracy992641
-Node: Try To Round995351
-Node: Setting precision996250
-Ref: table-predefined-precision-strings996947
-Node: Setting the rounding mode998777
-Ref: table-gawk-rounding-modes999151
-Ref: Setting the rounding mode-Footnote-11003082
-Node: Arbitrary Precision Integers1003261
-Ref: Arbitrary Precision Integers-Footnote-11006436
-Node: Checking for MPFR1006585
-Node: POSIX Floating Point Problems1008059
-Ref: POSIX Floating Point Problems-Footnote-11012344
-Node: Floating point summary1012382
-Node: Dynamic Extensions1014572
-Node: Extension Intro1016125
-Node: Plugin License1017391
-Node: Extension Mechanism Outline1018188
-Ref: figure-load-extension1018627
-Ref: figure-register-new-function1020192
-Ref: figure-call-new-function1021284
-Node: Extension API Description1023346
-Node: Extension API Functions Introduction1025059
-Ref: table-api-std-headers1026895
-Node: General Data Types1031144
-Ref: General Data Types-Footnote-11039774
-Node: Memory Allocation Functions1040073
-Ref: Memory Allocation Functions-Footnote-11044574
-Node: Constructor Functions1044673
-Node: API Ownership of MPFR and GMP Values1048139
-Node: Registration Functions1049452
-Node: Extension Functions1050152
-Node: Exit Callback Functions1055474
-Node: Extension Version String1056724
-Node: Input Parsers1057387
-Node: Output Wrappers1070108
-Node: Two-way processors1074620
-Node: Printing Messages1076885
-Ref: Printing Messages-Footnote-11078056
-Node: Updating ERRNO1078209
-Node: Requesting Values1078948
-Ref: table-value-types-returned1079685
-Node: Accessing Parameters1080621
-Node: Symbol Table Access1081858
-Node: Symbol table by name1082370
-Ref: Symbol table by name-Footnote-11085394
-Node: Symbol table by cookie1085522
-Ref: Symbol table by cookie-Footnote-11089707
-Node: Cached values1089771
-Ref: Cached values-Footnote-11093307
-Node: Array Manipulation1093460
-Ref: Array Manipulation-Footnote-11094551
-Node: Array Data Types1094588
-Ref: Array Data Types-Footnote-11097246
-Node: Array Functions1097338
-Node: Flattening Arrays1101836
-Node: Creating Arrays1108812
-Node: Redirection API1113579
-Node: Extension API Variables1116412
-Node: Extension Versioning1117123
-Ref: gawk-api-version1117552
-Node: Extension GMP/MPFR Versioning1119283
-Node: Extension API Informational Variables1120911
-Node: Extension API Boilerplate1121984
-Node: Changes from API V11125958
-Node: Finding Extensions1127530
-Node: Extension Example1128089
-Node: Internal File Description1128887
-Node: Internal File Ops1132967
-Ref: Internal File Ops-Footnote-11144317
-Node: Using Internal File Ops1144457
-Ref: Using Internal File Ops-Footnote-11146840
-Node: Extension Samples1147114
-Node: Extension Sample File Functions1148643
-Node: Extension Sample Fnmatch1156292
-Node: Extension Sample Fork1157779
-Node: Extension Sample Inplace1158997
-Node: Extension Sample Ord1162623
-Node: Extension Sample Readdir1163459
-Ref: table-readdir-file-types1164348
-Node: Extension Sample Revout1165415
-Node: Extension Sample Rev2way1166004
-Node: Extension Sample Read write array1166744
-Node: Extension Sample Readfile1168686
-Node: Extension Sample Time1169781
-Node: Extension Sample API Tests1171533
-Node: gawkextlib1172025
-Node: Extension summary1174943
-Node: Extension Exercises1178645
-Node: Language History1179887
-Node: V7/SVR3.11181543
-Node: SVR41183695
-Node: POSIX1185129
-Node: BTL1186510
-Node: POSIX/GNU1187239
-Node: Feature History1193017
-Node: Common Extensions1210192
-Node: Ranges and Locales1211475
-Ref: Ranges and Locales-Footnote-11216091
-Ref: Ranges and Locales-Footnote-21216118
-Ref: Ranges and Locales-Footnote-31216353
-Node: Contributors1216576
-Node: History summary1222573
-Node: Installation1223953
-Node: Gawk Distribution1224897
-Node: Getting1225381
-Node: Extracting1226344
-Node: Distribution contents1227982
-Node: Unix Installation1234462
-Node: Quick Installation1235144
-Node: Compiling with MPFR1237625
-Node: Shell Startup Files1238317
-Node: Additional Configuration Options1239406
-Node: Configuration Philosophy1241721
-Node: Non-Unix Installation1244090
-Node: PC Installation1244550
-Node: PC Binary Installation1245388
-Node: PC Compiling1245823
-Node: PC Using1246940
-Node: Cygwin1250493
-Node: MSYS1251717
-Node: VMS Installation1252319
-Node: VMS Compilation1253110
-Ref: VMS Compilation-Footnote-11254339
-Node: VMS Dynamic Extensions1254397
-Node: VMS Installation Details1256082
-Node: VMS Running1258335
-Node: VMS GNV1262614
-Node: VMS Old Gawk1263349
-Node: Bugs1263820
-Node: Bug definition1264700
-Node: Bug address1267204
-Node: Usenet1270592
-Node: Performance bugs1271601
-Node: Asking for help1274522
-Node: Maintainers1276484
-Node: Other Versions1277678
-Node: Installation summary1285530
-Node: Notes1286894
-Node: Compatibility Mode1287688
-Node: Additions1288470
-Node: Accessing The Source1289395
-Node: Adding Code1290832
-Node: New Ports1297051
-Node: Derived Files1301426
-Ref: Derived Files-Footnote-11307086
-Ref: Derived Files-Footnote-21307121
-Ref: Derived Files-Footnote-31307719
-Node: Future Extensions1307833
-Node: Implementation Limitations1308491
-Node: Extension Design1309701
-Node: Old Extension Problems1310845
-Ref: Old Extension Problems-Footnote-11312363
-Node: Extension New Mechanism Goals1312420
-Ref: Extension New Mechanism Goals-Footnote-11315784
-Node: Extension Other Design Decisions1315973
-Node: Extension Future Growth1318086
-Node: Notes summary1318692
-Node: Basic Concepts1319850
-Node: Basic High Level1320531
-Ref: figure-general-flow1320813
-Ref: figure-process-flow1321498
-Ref: Basic High Level-Footnote-11324799
-Node: Basic Data Typing1324984
-Node: Glossary1328312
-Node: Copying1360197
-Node: GNU Free Documentation License1397740
-Node: Index1422860
+Ref: String Functions-Footnote-1574167
+Ref: String Functions-Footnote-2574295
+Ref: String Functions-Footnote-3574543
+Node: Gory Details574630
+Ref: table-sub-escapes576421
+Ref: table-sub-proposed577940
+Ref: table-posix-sub579303
+Ref: table-gensub-escapes580844
+Ref: Gory Details-Footnote-1581667
+Node: I/O Functions581821
+Ref: table-system-return-values588275
+Ref: I/O Functions-Footnote-1590355
+Ref: I/O Functions-Footnote-2590503
+Node: Time Functions590623
+Ref: Time Functions-Footnote-1601294
+Ref: Time Functions-Footnote-2601362
+Ref: Time Functions-Footnote-3601520
+Ref: Time Functions-Footnote-4601631
+Ref: Time Functions-Footnote-5601743
+Ref: Time Functions-Footnote-6601970
+Node: Bitwise Functions602236
+Ref: table-bitwise-ops602830
+Ref: Bitwise Functions-Footnote-1608893
+Ref: Bitwise Functions-Footnote-2609066
+Node: Type Functions609257
+Node: I18N Functions612120
+Node: User-defined613771
+Node: Definition Syntax614583
+Ref: Definition Syntax-Footnote-1620277
+Node: Function Example620348
+Ref: Function Example-Footnote-1623270
+Node: Function Calling623292
+Node: Calling A Function623880
+Node: Variable Scope624838
+Node: Pass By Value/Reference627832
+Node: Function Caveats630476
+Ref: Function Caveats-Footnote-1632523
+Node: Return Statement632643
+Node: Dynamic Typing635622
+Node: Indirect Calls636552
+Ref: Indirect Calls-Footnote-1646804
+Node: Functions Summary646932
+Node: Library Functions649637
+Ref: Library Functions-Footnote-1653244
+Ref: Library Functions-Footnote-2653387
+Node: Library Names653558
+Ref: Library Names-Footnote-1657225
+Ref: Library Names-Footnote-2657448
+Node: General Functions657534
+Node: Strtonum Function658716
+Node: Assert Function661738
+Node: Round Function665064
+Node: Cliff Random Function666604
+Node: Ordinal Functions667620
+Ref: Ordinal Functions-Footnote-1670683
+Ref: Ordinal Functions-Footnote-2670935
+Node: Join Function671145
+Ref: Join Function-Footnote-1672915
+Node: Getlocaltime Function673115
+Node: Readfile Function676857
+Node: Shell Quoting678834
+Node: Isnumeric Function680262
+Node: Data File Management681599
+Node: Filetrans Function682231
+Node: Rewind Function686327
+Node: File Checking688236
+Ref: File Checking-Footnote-1689570
+Node: Empty Files689771
+Node: Ignoring Assigns691750
+Node: Getopt Function693300
+Ref: Getopt Function-Footnote-1708523
+Node: Passwd Functions708723
+Ref: Passwd Functions-Footnote-1717562
+Node: Group Functions717650
+Ref: Group Functions-Footnote-1725548
+Node: Walking Arrays725755
+Node: Library Functions Summary728763
+Node: Library Exercises730169
+Node: Sample Programs730634
+Node: Running Examples731404
+Node: Clones732132
+Node: Cut Program733356
+Node: Egrep Program743496
+Node: Id Program752497
+Node: Split Program762444
+Ref: Split Program-Footnote-1772337
+Node: Tee Program772510
+Node: Uniq Program775300
+Node: Wc Program782888
+Node: Bytes vs. Characters783275
+Node: Using extensions784823
+Node: wc program785577
+Node: Miscellaneous Programs790442
+Node: Dupword Program791655
+Node: Alarm Program793685
+Node: Translate Program798540
+Ref: Translate Program-Footnote-1803105
+Node: Labels Program803375
+Ref: Labels Program-Footnote-1806726
+Node: Word Sorting806810
+Node: History Sorting810882
+Node: Extract Program813107
+Node: Simple Sed821161
+Node: Igawk Program824235
+Ref: Igawk Program-Footnote-1838566
+Ref: Igawk Program-Footnote-2838768
+Ref: Igawk Program-Footnote-3838890
+Node: Anagram Program839005
+Node: Signature Program842067
+Node: Programs Summary843314
+Node: Programs Exercises844528
+Ref: Programs Exercises-Footnote-1848658
+Node: Advanced Features848744
+Node: Nondecimal Data850811
+Node: Array Sorting852402
+Node: Controlling Array Traversal853102
+Ref: Controlling Array Traversal-Footnote-1861470
+Node: Array Sorting Functions861588
+Ref: Array Sorting Functions-Footnote-1866962
+Node: Two-way I/O867158
+Ref: Two-way I/O-Footnote-1874884
+Ref: Two-way I/O-Footnote-2875071
+Node: TCP/IP Networking875153
+Node: Profiling878271
+Node: Extension Philosophy887580
+Node: Advanced Features Summary889059
+Node: Internationalization891074
+Node: I18N and L10N892748
+Node: Explaining gettext893435
+Ref: Explaining gettext-Footnote-1899327
+Ref: Explaining gettext-Footnote-2899512
+Node: Programmer i18n899677
+Ref: Programmer i18n-Footnote-1904626
+Node: Translator i18n904675
+Node: String Extraction905469
+Ref: String Extraction-Footnote-1906601
+Node: Printf Ordering906687
+Ref: Printf Ordering-Footnote-1909473
+Node: I18N Portability909537
+Ref: I18N Portability-Footnote-1911993
+Node: I18N Example912056
+Ref: I18N Example-Footnote-1915331
+Ref: I18N Example-Footnote-2915404
+Node: Gawk I18N915513
+Node: I18N Summary916162
+Node: Debugger917503
+Node: Debugging918503
+Node: Debugging Concepts918944
+Node: Debugging Terms920753
+Node: Awk Debugging923328
+Ref: Awk Debugging-Footnote-1924273
+Node: Sample Debugging Session924405
+Node: Debugger Invocation924939
+Node: Finding The Bug926325
+Node: List of Debugger Commands932799
+Node: Breakpoint Control934132
+Node: Debugger Execution Control937826
+Node: Viewing And Changing Data941188
+Node: Execution Stack944729
+Node: Debugger Info946366
+Node: Miscellaneous Debugger Commands950437
+Node: Readline Support955499
+Node: Limitations956395
+Node: Debugging Summary958949
+Node: Namespaces960228
+Node: Global Namespace961339
+Node: Qualified Names962737
+Node: Default Namespace963736
+Node: Changing The Namespace964477
+Node: Naming Rules966091
+Node: Internal Name Management967939
+Node: Namespace Example968981
+Node: Namespace And Features971543
+Node: Namespace Summary972978
+Node: Arbitrary Precision Arithmetic974455
+Node: Computer Arithmetic975942
+Ref: table-numeric-ranges979708
+Ref: table-floating-point-ranges980201
+Ref: Computer Arithmetic-Footnote-1980859
+Node: Math Definitions980916
+Ref: table-ieee-formats984232
+Ref: Math Definitions-Footnote-1984835
+Node: MPFR features984940
+Node: FP Math Caution986658
+Ref: FP Math Caution-Footnote-1987730
+Node: Inexactness of computations988099
+Node: Inexact representation989059
+Node: Comparing FP Values990419
+Node: Errors accumulate991660
+Node: Getting Accuracy993093
+Node: Try To Round995803
+Node: Setting precision996702
+Ref: table-predefined-precision-strings997399
+Node: Setting the rounding mode999229
+Ref: table-gawk-rounding-modes999603
+Ref: Setting the rounding mode-Footnote-11003534
+Node: Arbitrary Precision Integers1003713
+Ref: Arbitrary Precision Integers-Footnote-11006888
+Node: Checking for MPFR1007037
+Node: POSIX Floating Point Problems1008511
+Ref: POSIX Floating Point Problems-Footnote-11012796
+Node: Floating point summary1012834
+Node: Dynamic Extensions1015024
+Node: Extension Intro1016577
+Node: Plugin License1017843
+Node: Extension Mechanism Outline1018640
+Ref: figure-load-extension1019079
+Ref: figure-register-new-function1020644
+Ref: figure-call-new-function1021736
+Node: Extension API Description1023798
+Node: Extension API Functions Introduction1025511
+Ref: table-api-std-headers1027347
+Node: General Data Types1031596
+Ref: General Data Types-Footnote-11040226
+Node: Memory Allocation Functions1040525
+Ref: Memory Allocation Functions-Footnote-11045026
+Node: Constructor Functions1045125
+Node: API Ownership of MPFR and GMP Values1048591
+Node: Registration Functions1049904
+Node: Extension Functions1050604
+Node: Exit Callback Functions1055926
+Node: Extension Version String1057176
+Node: Input Parsers1057839
+Node: Output Wrappers1070560
+Node: Two-way processors1075072
+Node: Printing Messages1077337
+Ref: Printing Messages-Footnote-11078508
+Node: Updating ERRNO1078661
+Node: Requesting Values1079400
+Ref: table-value-types-returned1080137
+Node: Accessing Parameters1081073
+Node: Symbol Table Access1082310
+Node: Symbol table by name1082822
+Ref: Symbol table by name-Footnote-11085846
+Node: Symbol table by cookie1085974
+Ref: Symbol table by cookie-Footnote-11090159
+Node: Cached values1090223
+Ref: Cached values-Footnote-11093759
+Node: Array Manipulation1093912
+Ref: Array Manipulation-Footnote-11095003
+Node: Array Data Types1095040
+Ref: Array Data Types-Footnote-11097698
+Node: Array Functions1097790
+Node: Flattening Arrays1102288
+Node: Creating Arrays1109264
+Node: Redirection API1114031
+Node: Extension API Variables1116864
+Node: Extension Versioning1117575
+Ref: gawk-api-version1118004
+Node: Extension GMP/MPFR Versioning1119735
+Node: Extension API Informational Variables1121363
+Node: Extension API Boilerplate1122436
+Node: Changes from API V11126410
+Node: Finding Extensions1127982
+Node: Extension Example1128541
+Node: Internal File Description1129339
+Node: Internal File Ops1133419
+Ref: Internal File Ops-Footnote-11144769
+Node: Using Internal File Ops1144909
+Ref: Using Internal File Ops-Footnote-11147292
+Node: Extension Samples1147566
+Node: Extension Sample File Functions1149095
+Node: Extension Sample Fnmatch1156744
+Node: Extension Sample Fork1158231
+Node: Extension Sample Inplace1159449
+Node: Extension Sample Ord1163075
+Node: Extension Sample Readdir1163911
+Ref: table-readdir-file-types1164800
+Node: Extension Sample Revout1165867
+Node: Extension Sample Rev2way1166456
+Node: Extension Sample Read write array1167196
+Node: Extension Sample Readfile1169138
+Node: Extension Sample Time1170233
+Node: Extension Sample API Tests1171985
+Node: gawkextlib1172477
+Node: Extension summary1175395
+Node: Extension Exercises1179097
+Node: Language History1180339
+Node: V7/SVR3.11181995
+Node: SVR41184147
+Node: POSIX1185581
+Node: BTL1186962
+Node: POSIX/GNU1187691
+Node: Feature History1193469
+Node: Common Extensions1210644
+Node: Ranges and Locales1211927
+Ref: Ranges and Locales-Footnote-11216543
+Ref: Ranges and Locales-Footnote-21216570
+Ref: Ranges and Locales-Footnote-31216805
+Node: Contributors1217028
+Node: History summary1223025
+Node: Installation1224405
+Node: Gawk Distribution1225349
+Node: Getting1225833
+Node: Extracting1226796
+Node: Distribution contents1228434
+Node: Unix Installation1234914
+Node: Quick Installation1235596
+Node: Compiling with MPFR1238077
+Node: Shell Startup Files1238769
+Node: Additional Configuration Options1239858
+Node: Configuration Philosophy1242173
+Node: Non-Unix Installation1244542
+Node: PC Installation1245002
+Node: PC Binary Installation1245840
+Node: PC Compiling1246275
+Node: PC Using1247392
+Node: Cygwin1250945
+Node: MSYS1252169
+Node: VMS Installation1252771
+Node: VMS Compilation1253562
+Ref: VMS Compilation-Footnote-11254791
+Node: VMS Dynamic Extensions1254849
+Node: VMS Installation Details1256534
+Node: VMS Running1258787
+Node: VMS GNV1263066
+Node: VMS Old Gawk1263801
+Node: Bugs1264272
+Node: Bug definition1265152
+Node: Bug address1267656
+Node: Usenet1271044
+Node: Performance bugs1272053
+Node: Asking for help1274974
+Node: Maintainers1276936
+Node: Other Versions1278130
+Node: Installation summary1285982
+Node: Notes1287346
+Node: Compatibility Mode1288140
+Node: Additions1288922
+Node: Accessing The Source1289847
+Node: Adding Code1291284
+Node: New Ports1297503
+Node: Derived Files1301878
+Ref: Derived Files-Footnote-11307538
+Ref: Derived Files-Footnote-21307573
+Ref: Derived Files-Footnote-31308171
+Node: Future Extensions1308285
+Node: Implementation Limitations1308943
+Node: Extension Design1310153
+Node: Old Extension Problems1311297
+Ref: Old Extension Problems-Footnote-11312815
+Node: Extension New Mechanism Goals1312872
+Ref: Extension New Mechanism Goals-Footnote-11316236
+Node: Extension Other Design Decisions1316425
+Node: Extension Future Growth1318538
+Node: Notes summary1319144
+Node: Basic Concepts1320302
+Node: Basic High Level1320983
+Ref: figure-general-flow1321265
+Ref: figure-process-flow1321950
+Ref: Basic High Level-Footnote-11325251
+Node: Basic Data Typing1325436
+Node: Glossary1328764
+Node: Copying1360649
+Node: GNU Free Documentation License1398192
+Node: Index1423312
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 0f424237..c296ac8e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -59,7 +59,7 @@
 @c applies to and all the info about who's publishing this edition
 
 @c These apply across the board.
-@set UPDATE-MONTH January, 2021
+@set UPDATE-MONTH July, 2021
 @set VERSION 5.1
 @set PATCHLEVEL 0
 
@@ -18668,6 +18668,9 @@ You may use them as the first argument, but only if providing a second
 array to use for the actual sorting.
 @end quotation
 
+You are allowed to use the same array for both the @var{source} and @var{dest}
+arguments, but doing so only makes sense if you're also supplying the third argument.
+
 @item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{) #}
 @cindexgawkfunc{gensub}
 @cindex search and replace in strings
@@ -29889,6 +29892,12 @@ there is only one copy of the original array elements' data, even though
 both arrays use the values.
 @end quotation
 
+You may use the same array for both the first and second arguments to
+@code{asort()} and @code{asorti()}.  Doing so only makes sense if you
+are also supplying the third argument, since @command{awk} doesn't
+provide a way to pass that third argument without also passing the first
+and second ones.
+
 @c Document It And Call It A Feature. Sigh.
 @cindex @command{gawk} @subentry @code{IGNORECASE} variable in
 @cindex arrays @subentry sorting @subentry @code{IGNORECASE} variable and
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 897098c0..3fd1f06c 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -54,7 +54,7 @@
 @c applies to and all the info about who's publishing this edition
 
 @c These apply across the board.
-@set UPDATE-MONTH January, 2021
+@set UPDATE-MONTH July, 2021
 @set VERSION 5.1
 @set PATCHLEVEL 0
 
@@ -17809,6 +17809,9 @@ You may use them as the first argument, but only if providing a second
 array to use for the actual sorting.
 @end quotation
 
+You are allowed to use the same array for both the @var{source} and @var{dest}
+arguments, but doing so only makes sense if you're also supplying the third argument.
+
 @item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{) #}
 @cindexgawkfunc{gensub}
 @cindex search and replace in strings
@@ -28771,6 +28774,12 @@ there is only one copy of the original array elements' data, even though
 both arrays use the values.
 @end quotation
 
+You may use the same array for both the first and second arguments to
+@code{asort()} and @code{asorti()}.  Doing so only makes sense if you
+are also supplying the third argument, since @command{awk} doesn't
+provide a way to pass that third argument without also passing the first
+and second ones.
+
 @c Document It And Call It A Feature. Sigh.
 @cindex @command{gawk} @subentry @code{IGNORECASE} variable in
 @cindex arrays @subentry sorting @subentry @code{IGNORECASE} variable and