Merge branch 'gawk-5.1-stable'

8 files changed, 1339 insertions, 780 deletions

diff --git a/ChangeLog b/ChangeLog
index ec59123a..42a49ed4 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/NEWS b/NEWS
index a61e325f..9d395d30 100644
--- a/NEWS
+++ b/NEWS
@@ -70,7 +70,10 @@ Changes from 5.1.0 to 5.1.1
 13. The "no effect" lint warnings have been fixed up and now behave
     more sanely.
 
-14. There have been numerous minor code cleanups and bug fixes. See the
+14. The manual has been updated with much more information about what is
+    and is not a bug, and the changes in the gawk mailing lists.
+
+15. There have been numerous minor code cleanups and bug fixes. See the
     ChangeLog for details.
 
 Changes from 5.0.1 to 5.1.0
diff --git a/array.c b/array.c
index 58ca2c5e..cbed1254 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 a960b928..089e0c03 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,16 @@
+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
+	a bug, as well as of the new help-gawk@gnu.org list and how
+	things are now managed.
+
 2021-06-30         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* texinfo.tex: Updated from GNULIB.
diff --git a/doc/gawk.1 b/doc/gawk.1
index 6c72a887..b22a9485 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -13,7 +13,7 @@
 .		if \w'\(rq' .ds rq "\(rq
 .	\}
 .\}
-.TH GAWK 1 "May 30 2021" "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
diff --git a/doc/gawk.info b/doc/gawk.info
index 0db5773e..a382fcb2 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -688,9 +688,11 @@ in (a) below.  A copy of the license is included in the section entitled
 * VMS Old Gawk::                        An old version comes with some VMS
                                         systems.
 * Bugs::                                Reporting Problems and Bugs.
+* Bug definition::                      Defining what is and is not a bug.
 * Bug address::                         Where to send reports to.
 * Usenet::                              Where not to send reports to.
 * Performance bugs::                    What to do if you think there is a performance issue.
+* Asking for help::                     Dealing with non-bug questions.
 * Maintainers::                         Maintainers of non-*nix ports.
 * Other Versions::                      Other freely available 'awk'
                                         implementations.
@@ -13077,6 +13079,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'
@@ -21374,6 +21380,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;
@@ -31535,41 +31546,129 @@ might well want to fix it.
 
 * Menu:
 
+* Bug definition::              Defining what is and is not a bug.
 * Bug address::                 Where to send reports to.
 * Usenet::                      Where not to send reports to.
 * Performance bugs::            What to do if you think there is a performance issue.
+* Asking for help::             Dealing with non-bug questions.
 * Maintainers::                 Maintainers of non-*nix ports.
 
 
-File: gawk.info,  Node: Bug address,  Next: Usenet,  Up: Bugs
+File: gawk.info,  Node: Bug definition,  Next: Bug address,  Up: Bugs
+
+B.4.1 Defining What Is and What Is Not A Bug
+--------------------------------------------
+
+Before talking about reporting bugs, let's define what is a bug, and
+what is not.
+
+   A bug is:
+
+   * When 'gawk' behaves differently from what's described in the POSIX
+     standard, and that difference is not mentioned in this Info file as
+     being done on purpose.
+
+   * When 'gawk' behaves differently from what's described in this Info
+     file.
+
+   * When 'gawk' behaves differently from other 'awk' implementations in
+     particular circumstances, and that behavior cannot be attributed to
+     an additional feature in 'gawk'.
+
+   * Something that is obviously wrong, such as a core dump.
+
+   * When this Info file is unclear or ambiguous about a particular
+     feature's behavior.
+
+   The following things are _not_ bugs, and should not be reported to
+the bug mailing list.  You can ask about them on the "help" mailing list
+(*note Asking for help::), but don't be surprised if you get an answer
+of the form "that's how 'gawk' behaves and it isn't going to change."
+
+   * Missing features, for any definition of "feature".  For example,
+     additional built-in arithmetic functions, or additional ways to
+     split fields or records, or anything else.
+
+     The number of features that 'gawk' does _not_ have is by definition
+     infinite.  It cannot be all things to all people.
+
+   * Behaviors that are defined by the POSIX standard and/or for
+     historical compatibility with Unix 'awk'.  Even if you happen to
+     dislike those behaviors, they're not going to change: changing them
+     would break millions of existing 'awk' programs.
+
+   * Behaviors that differ from how it's done in other languages.  'awk'
+     and 'gawk' stand on their own and do not have to follow the crowd.
+     This is particularly true when the requested behavior change would
+     break backwards compatibility.
+
+   * Documentation issues of the form "the manual doesn't tell me how to
+     do XYZ." The manual is not a cookbook to solve every little problem
+     you may have.
 
-B.4.1 Submitting Bug Reports
+   * General questions and discussion about 'awk' programming or why
+     'gawk' behaves the way it does.  For that use the "help" mailing
+     list: see *note Asking for help::.
+
+   For more information, see 'Fork My Code, Please!--An Open Letter To
+Those of You Who Are Unhappy' (http://www.skeeve.com/fork-my-code.html),
+by Arnold Robbins and Chet Ramey.
+
+
+File: gawk.info,  Node: Bug address,  Next: Usenet,  Prev: Bug definition,  Up: Bugs
+
+B.4.2 Submitting Bug Reports
 ----------------------------
 
 Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of 'gawk'.  Many bugs
-(usually subtle ones) are fixed at each release, and if yours is out of
-date, the problem may already have been solved.
-
-   Second, please see if setting the environment variable 'LC_ALL' to
-'LC_ALL=C' causes things to behave as you expect.  If so, it's a locale
-issue, and may or may not really be a bug.
-
-   Third, carefully reread the documentation and see if it says you can
-do what you're trying to do.  If it's not clear whether you should be
-able to do something or not, report that too; it's a bug in the
-documentation!
-
-   Finally, before reporting a bug or trying to fix it yourself, try to
-isolate it to the smallest possible 'awk' program and input data file
-that reproduce the problem.  Then send us the program and data file,
-some idea of what kind of Unix system you're using, the compiler you
-used to compile 'gawk', and the exact results 'gawk' gave you.  Also say
-what you expected to occur; this helps us decide whether the problem is
-really in the documentation.
-
-   Make sure to include the version number of 'gawk' you are using.  You
-can get this information with the command 'gawk --version'.
+
+   Here are the steps for submitting a bug report.  Following them will
+make both your life and the lives of the maintainers much easier.
+
+  1. Make sure that what you want to report is appropriate.  *Note Bug
+     definition::.  If it's not, you are wasting your time and ours.
+
+  2. Verify that you have the latest version of 'gawk'.  Many bugs
+     (usually subtle ones) are fixed at each release, and if yours is
+     out of date, the problem may already have been solved.
+
+  3. Please see if setting the environment variable 'LC_ALL' to
+     'LC_ALL=C' causes things to behave as you expect.  If so, it's a
+     locale issue, and may or may not really be a bug.
+
+  4. Carefully reread the documentation and see if it says you can do
+     what you're trying to do.  If it's not clear whether you should be
+     able to do something or not, report that too; it's a bug in the
+     documentation!
+
+  5. Before reporting a bug or trying to fix it yourself, try to isolate
+     it to the smallest possible 'awk' program and input data file that
+     reproduce the problem.  Then send us:
+
+        * The program and data file.
+
+        * Some idea of what kind of Unix system you're using.
+
+        * The compiler you used to compile 'gawk'.
+
+        * The exact results 'gawk' gave you.  Also say what you expected
+          to occur; this helps us decide whether the problem is really
+          in the documentation.
+
+        * The version number of 'gawk' you are using.  You can get this
+          information with the command 'gawk --version'.
+
+  6. Do _not_ send screenshots.  Instead, use copy/paste to send text,
+     or send files.
+
+  7. Do send files as attachments, instead of inline.  This avoids
+     corruption by mailer programs out in the wilds of the Internet.
+
+  8. Please be sure to send all mail in _plain text_, not (or not
+     exclusively) in HTML.
+
+  9. _All email must be in English.  This is the only language
+     understood in common by all the maintainers._
 
    Once you have a precise problem description, send email to
 <bug-gawk@gnu.org>.
@@ -31577,10 +31676,7 @@ can get this information with the command 'gawk --version'.
    The 'gawk' maintainers subscribe to this address, and thus they will
 receive your bug report.  Although you can send mail to the maintainers
 directly, the bug reporting address is preferred because the email list
-is archived at the GNU Project.  _All email must be in English.  This is
-the only language understood in common by all the maintainers._  In
-addition, please be sure to send all mail in _plain text_, not (or not
-exclusively) in HTML.
+is archived at the GNU Project.
 
      NOTE: Many distributions of GNU/Linux and the various BSD-based
      operating systems have their own bug reporting systems.  If you
@@ -31594,11 +31690,6 @@ exclusively) in HTML.
      having everything at the GNU Project keeps things self-contained
      and not dependent on other organizations.
 
-   Non-bug suggestions are always welcome as well.  If you have
-questions about things that are unclear in the documentation or are just
-obscure features, ask on the bug list; we will try to help you out if we
-can.
-
    Please note: We ask that you follow the GNU Kind Communication
 Guidelines (https://gnu.org/philosophy/kind-communication.html) in your
 correspondence on the list (as well as off of it).
@@ -31606,7 +31697,7 @@ correspondence on the list (as well as off of it).
 
 File: gawk.info,  Node: Usenet,  Next: Performance bugs,  Prev: Bug address,  Up: Bugs
 
-B.4.2 Please Don't Post Bug Reports to USENET
+B.4.3 Please Don't Post Bug Reports to USENET
 ---------------------------------------------
 
      I gave up on Usenet a couple of years ago and haven't really looked
@@ -31627,9 +31718,9 @@ web forums.  The steps described here are the only officially recognized
 way for reporting bugs.  Really.
 
 
-File: gawk.info,  Node: Performance bugs,  Next: Maintainers,  Prev: Usenet,  Up: Bugs
+File: gawk.info,  Node: Performance bugs,  Next: Asking for help,  Prev: Usenet,  Up: Bugs
 
-B.4.3 What To Do If You Think There Is A Performance Issue
+B.4.4 What To Do If You Think There Is A Performance Issue
 ----------------------------------------------------------
 
 If you think that 'gawk' is too slow at doing a particular task, you
@@ -31651,10 +31742,10 @@ to follow:
      Unpack the source code in a new directory, and configure it:
 
           $ tar -xpzvf gawk-X.Y.Z.tar.gz
-          -| ...                                Output ommited
+          -| ...                                Output omitted
           $ cd gawk-X.Y.Z
           $ ./configure
-          -| ...                                Output ommited
+          -| ...                                Output omitted
 
   3. Edit the files 'Makefile' and 'support/Makefile'.  Change every
      instance of '-O2' or '-O' to '-pg'.  This causes 'gawk' to be
@@ -31663,7 +31754,7 @@ to follow:
   4. Compile the program by running the 'make' command:
 
           $ make
-          -| ...                                Output ommited
+          -| ...                                Output omitted
 
   5. Run the freshly compiled 'gawk' on a _real_ program, using _real_
      data.  Using an artificial program to try to time one particular
@@ -31676,6 +31767,8 @@ to follow:
      to measure where 'gawk' spends its time.  It should be at least 100
      megabytes in size.
 
+          $ ./gawk -f realprogram.awk realdata > /dev/null
+
   6. When done, you should have a file in the current directory named
      'gmon.out'.  Run the command 'gprof gawk gmon.out > gprof.out'.
 
@@ -31693,9 +31786,61 @@ to follow:
 you will just have to live with 'gawk' as it is.
 
 
-File: gawk.info,  Node: Maintainers,  Prev: Performance bugs,  Up: Bugs
+File: gawk.info,  Node: Asking for help,  Next: Maintainers,  Prev: Performance bugs,  Up: Bugs
+
+B.4.5 Where To Send Non-bug Questions
+-------------------------------------
+
+If you have questions related to 'awk' programming, or why 'gawk'
+behaves a certain way, or any other 'awk'- or 'gawk'-related issue,
+please _do not_ send it to the bug reporting address.
+
+   As of July, 2021, there is a separate mailing list for this purpose:
+<help-gawk@gnu.org>.  Anything that is not a bug report should be sent
+to that list.
+
+     NOTE: If you disregard these directions and send non-bug mails to
+     the bug list, you will be told to use the help list.  After two
+     such requests you will be silently _blacklisted_ from the bug list.
+
+   Please note: As with the bug list, we ask that you follow the GNU
+Kind Communication Guidelines
+(https://gnu.org/philosophy/kind-communication.html) in your
+correspondence on the list (as well as off of it).
+
+   If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy of Bob
+Proulx:
+
+_Subscribe by email_
+
+     Send an email message to <help-gawk-request@gnu.org> with
+     "subscribe" in the body of the message.  The subject does not
+     matter and is not used.
+
+_Subscribe by web form_
+
+     To use the web interface visit the list information page
+     (https://lists.gnu.org/mailman/listinfo/help-gawk).  Use the
+     subscribe form to fill out your email address and submit using the
+     'Subscribe' button.
+
+_Reply to the confirmation message_
+
+     In both cases then reply to the confirmation message that is sent
+     to your address in reply.
+
+   Bob mentions that you may also use email for subscribing and
+unsubscribing.  For example:
+
+     $ echo help | mailx -s request help-gawk-request@gnu.org
+     $ echo subscribe | mailx -s request help-gawk-request@gnu.org
+     $ echo unsubscribe | mailx -s request help-gawk-request@gnu.org
+
+
+File: gawk.info,  Node: Maintainers,  Prev: Asking for help,  Up: Bugs
 
-B.4.4 Reporting Problems with Non-Unix Ports
+B.4.6 Reporting Problems with Non-Unix Ports
 --------------------------------------------
 
 If you find bugs in one of the non-Unix ports of 'gawk', send an email
@@ -31791,8 +31936,8 @@ Unix 'awk'
      provide the core 'awk' functionality.  It also has a number of
      extensions.
 
-     The 'awk' translator is released under the GPL, and the library is
-     under the LGPL.
+     Both the 'awk' translator and the library are released under the
+     GPL.
 
      To get 'awka', go to <https://sourceforge.net/projects/awka>.
 
@@ -31933,6 +32078,10 @@ B.6 Summary
      'gawk', how it was compiled, and a short program and data file that
      demonstrate the problem.
 
+   * Non-bug emails should be sent to <help-gawk@gnu.org>.  Repeatedly
+     sending non-bug emails to the bug list will get you blacklisted
+     from it.
+
    * There are a number of other freely available 'awk' implementations.
      Many are POSIX-compliant; others are less so.
 
@@ -34913,7 +35062,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)
@@ -35295,7 +35444,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)
@@ -35305,7 +35454,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)
@@ -35354,7 +35503,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)
@@ -35600,7 +35749,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)
@@ -35621,8 +35770,8 @@ Index
                                                               (line  51)
 * buffers, flushing:                     I/O Functions.       (line  32)
 * buffers, flushing <1>:                 I/O Functions.       (line 168)
-* bug reports, email address, bug-gawk@gnu.org: Bug address.  (line  31)
-* bug-gawk@gnu.org bug reporting address: Bug address.        (line  31)
+* bug reports, email address, bug-gawk@gnu.org: Bug address.  (line  56)
+* bug-gawk@gnu.org bug reporting address: Bug address.        (line  56)
 * built-in functions:                    Functions.           (line   6)
 * built-in functions, evaluation order:  Calling Built-in.    (line  30)
 * BusyBox Awk:                           Other Versions.      (line  92)
@@ -35664,7 +35813,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.
@@ -35748,7 +35897,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)
@@ -35806,9 +35955,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)
@@ -35896,9 +36045,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)
@@ -36148,11 +36297,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.
@@ -36210,7 +36359,7 @@ Index
                                                               (line  48)
 * elements in arrays, deleting:          Delete.              (line   6)
 * email address for bug reports, bug-gawk@gnu.org: Bug address.
-                                                              (line  31)
+                                                              (line  56)
 * empty array elements:                  Reference to Elements.
                                                               (line  18)
 * empty pattern:                         Empty.               (line   6)
@@ -36351,7 +36500,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.
@@ -36483,7 +36632,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)
@@ -36520,7 +36669,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.
@@ -36682,7 +36831,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)
@@ -36722,7 +36871,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)
@@ -36806,8 +36955,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)
@@ -36853,7 +37002,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)
@@ -36874,7 +37023,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)
@@ -36900,7 +37049,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)
@@ -37012,9 +37161,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)
@@ -37104,15 +37253,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)
@@ -37242,9 +37391,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)
@@ -37353,7 +37502,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.
@@ -37416,8 +37565,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)
@@ -37471,7 +37620,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)
@@ -37492,7 +37641,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.
@@ -37710,7 +37859,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)
@@ -37735,7 +37884,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)
@@ -37765,7 +37914,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)
@@ -37791,8 +37940,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)
@@ -37874,9 +38023,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.
@@ -37912,7 +38061,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.
@@ -37982,13 +38131,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)
@@ -38023,8 +38172,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)
@@ -38039,19 +38188,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.
@@ -38064,9 +38213,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)
@@ -38127,8 +38276,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)
@@ -38160,9 +38309,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)
@@ -38361,609 +38510,611 @@ Index
 
 Tag Table:
 Node: Top1200
-Node: Foreword345332
-Node: Foreword449774
-Node: Preface51306
-Ref: Preface-Footnote-154165
-Ref: Preface-Footnote-254274
-Ref: Preface-Footnote-354508
-Node: History54650
-Node: Names57002
-Ref: Names-Footnote-158106
-Node: This Manual58253
-Ref: This Manual-Footnote-164892
-Node: Conventions64992
-Node: Manual History67361
-Ref: Manual History-Footnote-170358
-Ref: Manual History-Footnote-270399
-Node: How To Contribute70473
-Node: Acknowledgments71399
-Node: Getting Started76336
-Node: Running gawk78775
-Node: One-shot79965
-Node: Read Terminal81228
-Node: Long83221
-Node: Executable Scripts84734
-Ref: Executable Scripts-Footnote-187367
-Node: Comments87470
-Node: Quoting89954
-Node: DOS Quoting95480
-Node: Sample Data Files97536
-Node: Very Simple100131
-Node: Two Rules106233
-Node: More Complex108118
-Node: Statements/Lines110450
-Ref: Statements/Lines-Footnote-1114934
-Node: Other Features115199
-Node: When116135
-Ref: When-Footnote-1117889
-Node: Intro Summary117954
-Node: Invoking Gawk118838
-Node: Command Line120352
-Node: Options121150
-Ref: Options-Footnote-1139064
-Ref: Options-Footnote-2139295
-Node: Other Arguments139320
-Node: Naming Standard Input143331
-Node: Environment Variables144541
-Node: AWKPATH Variable145099
-Ref: AWKPATH Variable-Footnote-1148511
-Ref: AWKPATH Variable-Footnote-2148545
-Node: AWKLIBPATH Variable148916
-Ref: AWKLIBPATH Variable-Footnote-1150613
-Node: Other Environment Variables150988
-Node: Exit Status154940
-Node: Include Files155617
-Node: Loading Shared Libraries159307
-Node: Obsolete160735
-Node: Undocumented161427
-Node: Invoking Summary161724
-Node: Regexp164565
-Node: Regexp Usage166019
-Node: Escape Sequences168056
-Node: Regexp Operators174297
-Node: Regexp Operator Details174782
-Ref: Regexp Operator Details-Footnote-1182146
-Node: Interval Expressions182293
-Ref: Interval Expressions-Footnote-1183714
-Node: Bracket Expressions183812
-Ref: table-char-classes186288
-Node: Leftmost Longest189614
-Node: Computed Regexps190917
-Node: GNU Regexp Operators194344
-Node: Case-sensitivity198081
-Ref: Case-sensitivity-Footnote-1200947
-Ref: Case-sensitivity-Footnote-2201182
-Node: Regexp Summary201290
-Node: Reading Files202756
-Node: Records205025
-Node: awk split records206100
-Node: gawk split records210800
-Ref: gawk split records-Footnote-1215874
-Node: Fields215911
-Node: Nonconstant Fields218652
-Ref: Nonconstant Fields-Footnote-1220888
-Node: Changing Fields221092
-Node: Field Separators227123
-Node: Default Field Splitting229821
-Node: Regexp Field Splitting230939
-Node: Single Character Fields234616
-Node: Command Line Field Separator235676
-Node: Full Line Fields238894
-Ref: Full Line Fields-Footnote-1240416
-Ref: Full Line Fields-Footnote-2240462
-Node: Field Splitting Summary240563
-Node: Constant Size242637
-Node: Fixed width data243369
-Node: Skipping intervening246836
-Node: Allowing trailing data247634
-Node: Fields with fixed data248671
-Node: Splitting By Content250189
-Ref: Splitting By Content-Footnote-1253972
-Node: More CSV254135
-Node: Testing field creation255727
-Node: Multiple Line257352
-Node: Getline263629
-Node: Plain Getline266098
-Node: Getline/Variable268671
-Node: Getline/File269822
-Node: Getline/Variable/File271210
-Ref: Getline/Variable/File-Footnote-1272815
-Node: Getline/Pipe272903
-Node: Getline/Variable/Pipe275607
-Node: Getline/Coprocess276742
-Node: Getline/Variable/Coprocess278009
-Node: Getline Notes278751
-Node: Getline Summary281548
-Ref: table-getline-variants281972
-Node: Read Timeout282720
-Ref: Read Timeout-Footnote-1286626
-Node: Retrying Input286684
-Node: Command-line directories287883
-Node: Input Summary288789
-Node: Input Exercises291961
-Node: Printing292395
-Node: Print294229
-Node: Print Examples295686
-Node: Output Separators298466
-Node: OFMT300483
-Node: Printf301839
-Node: Basic Printf302624
-Node: Control Letters304198
-Node: Format Modifiers309360
-Node: Printf Examples315375
-Node: Redirection317861
-Node: Special FD324702
-Ref: Special FD-Footnote-1327870
-Node: Special Files327944
-Node: Other Inherited Files328561
-Node: Special Network329562
-Node: Special Caveats330422
-Node: Close Files And Pipes331371
-Ref: table-close-pipe-return-values338278
-Ref: Close Files And Pipes-Footnote-1339091
-Ref: Close Files And Pipes-Footnote-2339239
-Node: Nonfatal339391
-Node: Output Summary341729
-Node: Output Exercises342951
-Node: Expressions343630
-Node: Values344818
-Node: Constants345496
-Node: Scalar Constants346187
-Ref: Scalar Constants-Footnote-1348697
-Node: Nondecimal-numbers348947
-Node: Regexp Constants351948
-Node: Using Constant Regexps352474
-Node: Standard Regexp Constants353096
-Node: Strong Regexp Constants356284
-Node: Variables359296
-Node: Using Variables359953
-Node: Assignment Options361863
-Node: Conversion364334
-Node: Strings And Numbers364858
-Ref: Strings And Numbers-Footnote-1367921
-Node: Locale influences conversions368030
-Ref: table-locale-affects370788
-Node: All Operators371406
-Node: Arithmetic Ops372035
-Node: Concatenation374751
-Ref: Concatenation-Footnote-1377598
-Node: Assignment Ops377705
-Ref: table-assign-ops382696
-Node: Increment Ops384009
-Node: Truth Values and Conditions387469
-Node: Truth Values388543
-Node: Typing and Comparison389591
-Node: Variable Typing390411
-Ref: Variable Typing-Footnote-1396874
-Ref: Variable Typing-Footnote-2396946
-Node: Comparison Operators397023
-Ref: table-relational-ops397442
-Node: POSIX String Comparison400937
-Ref: POSIX String Comparison-Footnote-1402632
-Ref: POSIX String Comparison-Footnote-2402771
-Node: Boolean Ops402855
-Ref: Boolean Ops-Footnote-1407337
-Node: Conditional Exp407429
-Node: Function Calls409165
-Node: Precedence413042
-Node: Locales416701
-Node: Expressions Summary418333
-Node: Patterns and Actions420906
-Node: Pattern Overview422026
-Node: Regexp Patterns423703
-Node: Expression Patterns424245
-Node: Ranges428026
-Node: BEGIN/END431134
-Node: Using BEGIN/END431895
-Ref: Using BEGIN/END-Footnote-1434649
-Node: I/O And BEGIN/END434755
-Node: BEGINFILE/ENDFILE437068
-Node: Empty440299
-Node: Using Shell Variables440616
-Node: Action Overview442890
-Node: Statements445215
-Node: If Statement447063
-Node: While Statement448558
-Node: Do Statement450586
-Node: For Statement451734
-Node: Switch Statement454905
-Node: Break Statement457346
-Node: Continue Statement459438
-Node: Next Statement461265
-Node: Nextfile Statement463648
-Node: Exit Statement466337
-Node: Built-in Variables468740
-Node: User-modified469873
-Node: Auto-set477640
-Ref: Auto-set-Footnote-1494447
-Ref: Auto-set-Footnote-2494653
-Node: ARGC and ARGV494709
-Node: Pattern Action Summary498922
-Node: Arrays501352
-Node: Array Basics502681
-Node: Array Intro503525
-Ref: figure-array-elements505500
-Ref: Array Intro-Footnote-1508204
-Node: Reference to Elements508332
-Node: Assigning Elements510796
-Node: Array Example511287
-Node: Scanning an Array513046
-Node: Controlling Scanning516068
-Ref: Controlling Scanning-Footnote-1522524
-Node: Numeric Array Subscripts522840
-Node: Uninitialized Subscripts525024
-Node: Delete526643
-Ref: Delete-Footnote-1529395
-Node: Multidimensional529452
-Node: Multiscanning532547
-Node: Arrays of Arrays534138
-Node: Arrays Summary538906
-Node: Functions540999
-Node: Built-in542037
-Node: Calling Built-in543190
-Node: Boolean Functions545186
-Node: Numeric Functions545740
-Ref: Numeric Functions-Footnote-1549767
-Ref: Numeric Functions-Footnote-2550415
-Ref: Numeric Functions-Footnote-3550463
-Node: String Functions550735
-Ref: String Functions-Footnote-1574876
-Ref: String Functions-Footnote-2575004
-Ref: String Functions-Footnote-3575252
-Node: Gory Details575339
-Ref: table-sub-escapes577130
-Ref: table-sub-proposed578649
-Ref: table-posix-sub580012
-Ref: table-gensub-escapes581553
-Ref: Gory Details-Footnote-1582376
-Node: I/O Functions582530
-Ref: table-system-return-values588984
-Ref: I/O Functions-Footnote-1591064
-Ref: I/O Functions-Footnote-2591212
-Node: Time Functions591332
-Ref: Time Functions-Footnote-1602003
-Ref: Time Functions-Footnote-2602071
-Ref: Time Functions-Footnote-3602229
-Ref: Time Functions-Footnote-4602340
-Ref: Time Functions-Footnote-5602452
-Ref: Time Functions-Footnote-6602679
-Node: Bitwise Functions602945
-Ref: table-bitwise-ops603539
-Ref: Bitwise Functions-Footnote-1609602
-Ref: Bitwise Functions-Footnote-2609775
-Node: Type Functions609966
-Node: I18N Functions612920
-Node: User-defined614571
-Node: Definition Syntax615383
-Ref: Definition Syntax-Footnote-1621077
-Node: Function Example621148
-Ref: Function Example-Footnote-1624070
-Node: Function Calling624092
-Node: Calling A Function624680
-Node: Variable Scope625638
-Node: Pass By Value/Reference628632
-Node: Function Caveats631276
-Ref: Function Caveats-Footnote-1633323
-Node: Return Statement633443
-Node: Dynamic Typing636422
-Node: Indirect Calls637352
-Ref: Indirect Calls-Footnote-1647607
-Node: Functions Summary647735
-Node: Library Functions650440
-Ref: Library Functions-Footnote-1654047
-Ref: Library Functions-Footnote-2654190
-Node: Library Names654361
-Ref: Library Names-Footnote-1658028
-Ref: Library Names-Footnote-2658251
-Node: General Functions658337
-Node: Strtonum Function659519
-Node: Assert Function662541
-Node: Round Function665867
-Node: Cliff Random Function667407
-Node: Ordinal Functions668423
-Ref: Ordinal Functions-Footnote-1671486
-Ref: Ordinal Functions-Footnote-2671738
-Node: Join Function671948
-Ref: Join Function-Footnote-1673718
-Node: Getlocaltime Function673918
-Node: Readfile Function677660
-Node: Shell Quoting679637
-Node: Isnumeric Function681065
-Node: Data File Management682402
-Node: Filetrans Function683034
-Node: Rewind Function687130
-Node: File Checking689039
-Ref: File Checking-Footnote-1690373
-Node: Empty Files690574
-Node: Ignoring Assigns692553
-Node: Getopt Function694103
-Ref: Getopt Function-Footnote-1709326
-Node: Passwd Functions709526
-Ref: Passwd Functions-Footnote-1718365
-Node: Group Functions718453
-Ref: Group Functions-Footnote-1726351
-Node: Walking Arrays726558
-Node: Library Functions Summary729566
-Node: Library Exercises730972
-Node: Sample Programs731437
-Node: Running Examples732207
-Node: Clones732935
-Node: Cut Program734159
-Node: Egrep Program744299
-Node: Id Program753300
-Node: Split Program763247
-Ref: Split Program-Footnote-1773140
-Node: Tee Program773313
-Node: Uniq Program776103
-Node: Wc Program783691
-Node: Bytes vs. Characters784078
-Node: Using extensions785626
-Node: wc program786380
-Node: Miscellaneous Programs791245
-Node: Dupword Program792458
-Node: Alarm Program794488
-Node: Translate Program799343
-Ref: Translate Program-Footnote-1803908
-Node: Labels Program804178
-Ref: Labels Program-Footnote-1807529
-Node: Word Sorting807613
-Node: History Sorting811685
-Node: Extract Program813910
-Node: Simple Sed821964
-Node: Igawk Program825038
-Ref: Igawk Program-Footnote-1839369
-Ref: Igawk Program-Footnote-2839571
-Ref: Igawk Program-Footnote-3839693
-Node: Anagram Program839808
-Node: Signature Program842870
-Node: Programs Summary844117
-Node: Programs Exercises845331
-Ref: Programs Exercises-Footnote-1849461
-Node: Advanced Features849547
-Node: Nondecimal Data851678
-Node: Boolean Typed Values853276
-Node: Array Sorting855157
-Node: Controlling Array Traversal855862
-Ref: Controlling Array Traversal-Footnote-1864230
-Node: Array Sorting Functions864348
-Ref: Array Sorting Functions-Footnote-1869439
-Node: Two-way I/O869635
-Ref: Two-way I/O-Footnote-1877361
-Ref: Two-way I/O-Footnote-2877548
-Node: TCP/IP Networking877630
-Node: Profiling880748
-Node: Extension Philosophy890057
-Node: Advanced Features Summary891536
-Node: Internationalization893551
-Node: I18N and L10N895225
-Node: Explaining gettext895912
-Ref: Explaining gettext-Footnote-1901804
-Ref: Explaining gettext-Footnote-2901989
-Node: Programmer i18n902154
-Ref: Programmer i18n-Footnote-1907103
-Node: Translator i18n907152
-Node: String Extraction907946
-Ref: String Extraction-Footnote-1909078
-Node: Printf Ordering909164
-Ref: Printf Ordering-Footnote-1911950
-Node: I18N Portability912014
-Ref: I18N Portability-Footnote-1914470
-Node: I18N Example914533
-Ref: I18N Example-Footnote-1917808
-Ref: I18N Example-Footnote-2917881
-Node: Gawk I18N917990
-Node: I18N Summary918639
-Node: Debugger919980
-Node: Debugging920980
-Node: Debugging Concepts921421
-Node: Debugging Terms923230
-Node: Awk Debugging925805
-Ref: Awk Debugging-Footnote-1926750
-Node: Sample Debugging Session926882
-Node: Debugger Invocation927416
-Node: Finding The Bug928802
-Node: List of Debugger Commands935276
-Node: Breakpoint Control936609
-Node: Debugger Execution Control940303
-Node: Viewing And Changing Data943665
-Node: Execution Stack947206
-Node: Debugger Info948843
-Node: Miscellaneous Debugger Commands952914
-Node: Readline Support957976
-Node: Limitations958872
-Node: Debugging Summary961426
-Node: Namespaces962705
-Node: Global Namespace963816
-Node: Qualified Names965214
-Node: Default Namespace966213
-Node: Changing The Namespace966954
-Node: Naming Rules968568
-Node: Internal Name Management970416
-Node: Namespace Example971458
-Node: Namespace And Features974020
-Node: Namespace Summary975455
-Node: Arbitrary Precision Arithmetic976932
-Node: Computer Arithmetic978419
-Ref: table-numeric-ranges982185
-Ref: table-floating-point-ranges982678
-Ref: Computer Arithmetic-Footnote-1983336
-Node: Math Definitions983393
-Ref: table-ieee-formats986369
-Node: MPFR features986936
-Node: FP Math Caution988654
-Ref: FP Math Caution-Footnote-1989726
-Node: Inexactness of computations990095
-Node: Inexact representation991126
-Node: Comparing FP Values992486
-Node: Errors accumulate993727
-Node: Strange values995183
-Ref: Strange values-Footnote-1997771
-Node: Getting Accuracy997876
-Node: Try To Round1000586
-Node: Setting precision1001485
-Ref: table-predefined-precision-strings1002182
-Node: Setting the rounding mode1004012
-Ref: table-gawk-rounding-modes1004386
-Ref: Setting the rounding mode-Footnote-11008317
-Node: Arbitrary Precision Integers1008496
-Ref: Arbitrary Precision Integers-Footnote-11011671
-Node: Checking for MPFR1011820
-Node: POSIX Floating Point Problems1013294
-Ref: POSIX Floating Point Problems-Footnote-11017579
-Node: Floating point summary1017617
-Node: Dynamic Extensions1019807
-Node: Extension Intro1021360
-Node: Plugin License1022626
-Node: Extension Mechanism Outline1023423
-Ref: figure-load-extension1023862
-Ref: figure-register-new-function1025427
-Ref: figure-call-new-function1026519
-Node: Extension API Description1028581
-Node: Extension API Functions Introduction1030294
-Ref: table-api-std-headers1032130
-Node: General Data Types1036379
-Ref: General Data Types-Footnote-11045085
-Node: Memory Allocation Functions1045384
-Ref: Memory Allocation Functions-Footnote-11049885
-Node: Constructor Functions1049984
-Node: API Ownership of MPFR and GMP Values1053637
-Node: Registration Functions1054950
-Node: Extension Functions1055650
-Node: Exit Callback Functions1060972
-Node: Extension Version String1062222
-Node: Input Parsers1062885
-Node: Output Wrappers1075606
-Node: Two-way processors1080118
-Node: Printing Messages1082383
-Ref: Printing Messages-Footnote-11083554
-Node: Updating ERRNO1083707
-Node: Requesting Values1084446
-Ref: table-value-types-returned1085183
-Node: Accessing Parameters1086291
-Node: Symbol Table Access1087528
-Node: Symbol table by name1088040
-Ref: Symbol table by name-Footnote-11091064
-Node: Symbol table by cookie1091192
-Ref: Symbol table by cookie-Footnote-11095377
-Node: Cached values1095441
-Ref: Cached values-Footnote-11098977
-Node: Array Manipulation1099130
-Ref: Array Manipulation-Footnote-11100221
-Node: Array Data Types1100258
-Ref: Array Data Types-Footnote-11102916
-Node: Array Functions1103008
-Node: Flattening Arrays1107506
-Node: Creating Arrays1114482
-Node: Redirection API1119249
-Node: Extension API Variables1122082
-Node: Extension Versioning1122793
-Ref: gawk-api-version1123222
-Node: Extension GMP/MPFR Versioning1124953
-Node: Extension API Informational Variables1126581
-Node: Extension API Boilerplate1127654
-Node: Changes from API V11131628
-Node: Finding Extensions1133200
-Node: Extension Example1133759
-Node: Internal File Description1134557
-Node: Internal File Ops1138637
-Ref: Internal File Ops-Footnote-11149987
-Node: Using Internal File Ops1150127
-Ref: Using Internal File Ops-Footnote-11152510
-Node: Extension Samples1152784
-Node: Extension Sample File Functions1154313
-Node: Extension Sample Fnmatch1161962
-Node: Extension Sample Fork1163449
-Node: Extension Sample Inplace1164667
-Node: Extension Sample Ord1168293
-Node: Extension Sample Readdir1169129
-Ref: table-readdir-file-types1170018
-Node: Extension Sample Revout1171085
-Node: Extension Sample Rev2way1171674
-Node: Extension Sample Read write array1172414
-Node: Extension Sample Readfile1174356
-Node: Extension Sample Time1175451
-Node: Extension Sample API Tests1177203
-Node: gawkextlib1177695
-Node: Extension summary1180613
-Node: Extension Exercises1184315
-Node: Language History1185557
-Node: V7/SVR3.11187213
-Node: SVR41189365
-Node: POSIX1190799
-Node: BTL1192180
-Node: POSIX/GNU1192909
-Node: Feature History1198687
-Node: Common Extensions1215862
-Node: Ranges and Locales1217145
-Ref: Ranges and Locales-Footnote-11221761
-Ref: Ranges and Locales-Footnote-21221788
-Ref: Ranges and Locales-Footnote-31222023
-Node: Contributors1222246
-Node: History summary1228243
-Node: Installation1229623
-Node: Gawk Distribution1230567
-Node: Getting1231051
-Node: Extracting1232014
-Node: Distribution contents1233652
-Node: Unix Installation1240132
-Node: Quick Installation1240814
-Node: Compiling with MPFR1243295
-Node: Shell Startup Files1243987
-Node: Additional Configuration Options1245076
-Node: Configuration Philosophy1247391
-Node: Non-Unix Installation1249760
-Node: PC Installation1250220
-Node: PC Binary Installation1251058
-Node: PC Compiling1251493
-Node: PC Using1252610
-Node: Cygwin1256163
-Node: MSYS1257387
-Node: VMS Installation1257989
-Node: VMS Compilation1258780
-Ref: VMS Compilation-Footnote-11260009
-Node: VMS Dynamic Extensions1260067
-Node: VMS Installation Details1261752
-Node: VMS Running1264005
-Node: VMS GNV1268284
-Node: VMS Old Gawk1269019
-Node: Bugs1269490
-Node: Bug address1270239
-Node: Usenet1273221
-Node: Performance bugs1274230
-Node: Maintainers1277087
-Node: Other Versions1278282
-Node: Installation summary1286147
-Node: Notes1287356
-Node: Compatibility Mode1288150
-Node: Additions1288932
-Node: Accessing The Source1289857
-Node: Adding Code1291294
-Node: New Ports1297513
-Node: Derived Files1301888
-Ref: Derived Files-Footnote-11307548
-Ref: Derived Files-Footnote-21307583
-Ref: Derived Files-Footnote-31308181
-Node: Future Extensions1308295
-Node: Implementation Limitations1308953
-Node: Extension Design1310163
-Node: Old Extension Problems1311307
-Ref: Old Extension Problems-Footnote-11312825
-Node: Extension New Mechanism Goals1312882
-Ref: Extension New Mechanism Goals-Footnote-11316246
-Node: Extension Other Design Decisions1316435
-Node: Extension Future Growth1318548
-Node: Notes summary1319154
-Node: Basic Concepts1320312
-Node: Basic High Level1320993
-Ref: figure-general-flow1321275
-Ref: figure-process-flow1321960
-Ref: Basic High Level-Footnote-11325261
-Node: Basic Data Typing1325446
-Node: Glossary1328774
-Node: Copying1360661
-Node: GNU Free Documentation License1398204
-Node: Index1423324
+Node: Foreword345479
+Node: Foreword449921
+Node: Preface51453
+Ref: Preface-Footnote-154312
+Ref: Preface-Footnote-254421
+Ref: Preface-Footnote-354655
+Node: History54797
+Node: Names57149
+Ref: Names-Footnote-158253
+Node: This Manual58400
+Ref: This Manual-Footnote-165039
+Node: Conventions65139
+Node: Manual History67508
+Ref: Manual History-Footnote-170505
+Ref: Manual History-Footnote-270546
+Node: How To Contribute70620
+Node: Acknowledgments71546
+Node: Getting Started76483
+Node: Running gawk78922
+Node: One-shot80112
+Node: Read Terminal81375
+Node: Long83368
+Node: Executable Scripts84881
+Ref: Executable Scripts-Footnote-187514
+Node: Comments87617
+Node: Quoting90101
+Node: DOS Quoting95627
+Node: Sample Data Files97683
+Node: Very Simple100278
+Node: Two Rules106380
+Node: More Complex108265
+Node: Statements/Lines110597
+Ref: Statements/Lines-Footnote-1115081
+Node: Other Features115346
+Node: When116282
+Ref: When-Footnote-1118036
+Node: Intro Summary118101
+Node: Invoking Gawk118985
+Node: Command Line120499
+Node: Options121297
+Ref: Options-Footnote-1139211
+Ref: Options-Footnote-2139442
+Node: Other Arguments139467
+Node: Naming Standard Input143478
+Node: Environment Variables144688
+Node: AWKPATH Variable145246
+Ref: AWKPATH Variable-Footnote-1148658
+Ref: AWKPATH Variable-Footnote-2148692
+Node: AWKLIBPATH Variable149063
+Ref: AWKLIBPATH Variable-Footnote-1150760
+Node: Other Environment Variables151135
+Node: Exit Status155087
+Node: Include Files155764
+Node: Loading Shared Libraries159454
+Node: Obsolete160882
+Node: Undocumented161574
+Node: Invoking Summary161871
+Node: Regexp164712
+Node: Regexp Usage166166
+Node: Escape Sequences168203
+Node: Regexp Operators174444
+Node: Regexp Operator Details174929
+Ref: Regexp Operator Details-Footnote-1182293
+Node: Interval Expressions182440
+Ref: Interval Expressions-Footnote-1183861
+Node: Bracket Expressions183959
+Ref: table-char-classes186435
+Node: Leftmost Longest189761
+Node: Computed Regexps191064
+Node: GNU Regexp Operators194491
+Node: Case-sensitivity198228
+Ref: Case-sensitivity-Footnote-1201094
+Ref: Case-sensitivity-Footnote-2201329
+Node: Regexp Summary201437
+Node: Reading Files202903
+Node: Records205172
+Node: awk split records206247
+Node: gawk split records210947
+Ref: gawk split records-Footnote-1216021
+Node: Fields216058
+Node: Nonconstant Fields218799
+Ref: Nonconstant Fields-Footnote-1221035
+Node: Changing Fields221239
+Node: Field Separators227270
+Node: Default Field Splitting229968
+Node: Regexp Field Splitting231086
+Node: Single Character Fields234763
+Node: Command Line Field Separator235823
+Node: Full Line Fields239041
+Ref: Full Line Fields-Footnote-1240563
+Ref: Full Line Fields-Footnote-2240609
+Node: Field Splitting Summary240710
+Node: Constant Size242784
+Node: Fixed width data243516
+Node: Skipping intervening246983
+Node: Allowing trailing data247781
+Node: Fields with fixed data248818
+Node: Splitting By Content250336
+Ref: Splitting By Content-Footnote-1254119
+Node: More CSV254282
+Node: Testing field creation255874
+Node: Multiple Line257499
+Node: Getline263776
+Node: Plain Getline266245
+Node: Getline/Variable268818
+Node: Getline/File269969
+Node: Getline/Variable/File271357
+Ref: Getline/Variable/File-Footnote-1272962
+Node: Getline/Pipe273050
+Node: Getline/Variable/Pipe275754
+Node: Getline/Coprocess276889
+Node: Getline/Variable/Coprocess278156
+Node: Getline Notes278898
+Node: Getline Summary281695
+Ref: table-getline-variants282119
+Node: Read Timeout282867
+Ref: Read Timeout-Footnote-1286773
+Node: Retrying Input286831
+Node: Command-line directories288030
+Node: Input Summary288936
+Node: Input Exercises292108
+Node: Printing292542
+Node: Print294376
+Node: Print Examples295833
+Node: Output Separators298613
+Node: OFMT300630
+Node: Printf301986
+Node: Basic Printf302771
+Node: Control Letters304345
+Node: Format Modifiers309507
+Node: Printf Examples315522
+Node: Redirection318008
+Node: Special FD324849
+Ref: Special FD-Footnote-1328017
+Node: Special Files328091
+Node: Other Inherited Files328708
+Node: Special Network329709
+Node: Special Caveats330569
+Node: Close Files And Pipes331518
+Ref: table-close-pipe-return-values338425
+Ref: Close Files And Pipes-Footnote-1339238
+Ref: Close Files And Pipes-Footnote-2339386
+Node: Nonfatal339538
+Node: Output Summary341876
+Node: Output Exercises343098
+Node: Expressions343777
+Node: Values344965
+Node: Constants345643
+Node: Scalar Constants346334
+Ref: Scalar Constants-Footnote-1348844
+Node: Nondecimal-numbers349094
+Node: Regexp Constants352095
+Node: Using Constant Regexps352621
+Node: Standard Regexp Constants353243
+Node: Strong Regexp Constants356431
+Node: Variables359443
+Node: Using Variables360100
+Node: Assignment Options362010
+Node: Conversion364481
+Node: Strings And Numbers365005
+Ref: Strings And Numbers-Footnote-1368068
+Node: Locale influences conversions368177
+Ref: table-locale-affects370935
+Node: All Operators371553
+Node: Arithmetic Ops372182
+Node: Concatenation374898
+Ref: Concatenation-Footnote-1377745
+Node: Assignment Ops377852
+Ref: table-assign-ops382843
+Node: Increment Ops384156
+Node: Truth Values and Conditions387616
+Node: Truth Values388690
+Node: Typing and Comparison389738
+Node: Variable Typing390558
+Ref: Variable Typing-Footnote-1397021
+Ref: Variable Typing-Footnote-2397093
+Node: Comparison Operators397170
+Ref: table-relational-ops397589
+Node: POSIX String Comparison401084
+Ref: POSIX String Comparison-Footnote-1402779
+Ref: POSIX String Comparison-Footnote-2402918
+Node: Boolean Ops403002
+Ref: Boolean Ops-Footnote-1407484
+Node: Conditional Exp407576
+Node: Function Calls409312
+Node: Precedence413189
+Node: Locales416848
+Node: Expressions Summary418480
+Node: Patterns and Actions421053
+Node: Pattern Overview422173
+Node: Regexp Patterns423850
+Node: Expression Patterns424392
+Node: Ranges428173
+Node: BEGIN/END431281
+Node: Using BEGIN/END432042
+Ref: Using BEGIN/END-Footnote-1434796
+Node: I/O And BEGIN/END434902
+Node: BEGINFILE/ENDFILE437215
+Node: Empty440446
+Node: Using Shell Variables440763
+Node: Action Overview443037
+Node: Statements445362
+Node: If Statement447210
+Node: While Statement448705
+Node: Do Statement450733
+Node: For Statement451881
+Node: Switch Statement455052
+Node: Break Statement457493
+Node: Continue Statement459585
+Node: Next Statement461412
+Node: Nextfile Statement463795
+Node: Exit Statement466484
+Node: Built-in Variables468887
+Node: User-modified470020
+Node: Auto-set477787
+Ref: Auto-set-Footnote-1494594
+Ref: Auto-set-Footnote-2494800
+Node: ARGC and ARGV494856
+Node: Pattern Action Summary499069
+Node: Arrays501499
+Node: Array Basics502828
+Node: Array Intro503672
+Ref: figure-array-elements505647
+Ref: Array Intro-Footnote-1508351
+Node: Reference to Elements508479
+Node: Assigning Elements510943
+Node: Array Example511434
+Node: Scanning an Array513193
+Node: Controlling Scanning516215
+Ref: Controlling Scanning-Footnote-1522671
+Node: Numeric Array Subscripts522987
+Node: Uninitialized Subscripts525171
+Node: Delete526790
+Ref: Delete-Footnote-1529542
+Node: Multidimensional529599
+Node: Multiscanning532694
+Node: Arrays of Arrays534285
+Node: Arrays Summary539053
+Node: Functions541146
+Node: Built-in542184
+Node: Calling Built-in543337
+Node: Boolean Functions545333
+Node: Numeric Functions545887
+Ref: Numeric Functions-Footnote-1549914
+Ref: Numeric Functions-Footnote-2550562
+Ref: Numeric Functions-Footnote-3550610
+Node: String Functions550882
+Ref: String Functions-Footnote-1575192
+Ref: String Functions-Footnote-2575320
+Ref: String Functions-Footnote-3575568
+Node: Gory Details575655
+Ref: table-sub-escapes577446
+Ref: table-sub-proposed578965
+Ref: table-posix-sub580328
+Ref: table-gensub-escapes581869
+Ref: Gory Details-Footnote-1582692
+Node: I/O Functions582846
+Ref: table-system-return-values589300
+Ref: I/O Functions-Footnote-1591380
+Ref: I/O Functions-Footnote-2591528
+Node: Time Functions591648
+Ref: Time Functions-Footnote-1602319
+Ref: Time Functions-Footnote-2602387
+Ref: Time Functions-Footnote-3602545
+Ref: Time Functions-Footnote-4602656
+Ref: Time Functions-Footnote-5602768
+Ref: Time Functions-Footnote-6602995
+Node: Bitwise Functions603261
+Ref: table-bitwise-ops603855
+Ref: Bitwise Functions-Footnote-1609918
+Ref: Bitwise Functions-Footnote-2610091
+Node: Type Functions610282
+Node: I18N Functions613236
+Node: User-defined614887
+Node: Definition Syntax615699
+Ref: Definition Syntax-Footnote-1621393
+Node: Function Example621464
+Ref: Function Example-Footnote-1624386
+Node: Function Calling624408
+Node: Calling A Function624996
+Node: Variable Scope625954
+Node: Pass By Value/Reference628948
+Node: Function Caveats631592
+Ref: Function Caveats-Footnote-1633639
+Node: Return Statement633759
+Node: Dynamic Typing636738
+Node: Indirect Calls637668
+Ref: Indirect Calls-Footnote-1647923
+Node: Functions Summary648051
+Node: Library Functions650756
+Ref: Library Functions-Footnote-1654363
+Ref: Library Functions-Footnote-2654506
+Node: Library Names654677
+Ref: Library Names-Footnote-1658344
+Ref: Library Names-Footnote-2658567
+Node: General Functions658653
+Node: Strtonum Function659835
+Node: Assert Function662857
+Node: Round Function666183
+Node: Cliff Random Function667723
+Node: Ordinal Functions668739
+Ref: Ordinal Functions-Footnote-1671802
+Ref: Ordinal Functions-Footnote-2672054
+Node: Join Function672264
+Ref: Join Function-Footnote-1674034
+Node: Getlocaltime Function674234
+Node: Readfile Function677976
+Node: Shell Quoting679953
+Node: Isnumeric Function681381
+Node: Data File Management682718
+Node: Filetrans Function683350
+Node: Rewind Function687446
+Node: File Checking689355
+Ref: File Checking-Footnote-1690689
+Node: Empty Files690890
+Node: Ignoring Assigns692869
+Node: Getopt Function694419
+Ref: Getopt Function-Footnote-1709642
+Node: Passwd Functions709842
+Ref: Passwd Functions-Footnote-1718681
+Node: Group Functions718769
+Ref: Group Functions-Footnote-1726667
+Node: Walking Arrays726874
+Node: Library Functions Summary729882
+Node: Library Exercises731288
+Node: Sample Programs731753
+Node: Running Examples732523
+Node: Clones733251
+Node: Cut Program734475
+Node: Egrep Program744615
+Node: Id Program753616
+Node: Split Program763563
+Ref: Split Program-Footnote-1773456
+Node: Tee Program773629
+Node: Uniq Program776419
+Node: Wc Program784007
+Node: Bytes vs. Characters784394
+Node: Using extensions785942
+Node: wc program786696
+Node: Miscellaneous Programs791561
+Node: Dupword Program792774
+Node: Alarm Program794804
+Node: Translate Program799659
+Ref: Translate Program-Footnote-1804224
+Node: Labels Program804494
+Ref: Labels Program-Footnote-1807845
+Node: Word Sorting807929
+Node: History Sorting812001
+Node: Extract Program814226
+Node: Simple Sed822280
+Node: Igawk Program825354
+Ref: Igawk Program-Footnote-1839685
+Ref: Igawk Program-Footnote-2839887
+Ref: Igawk Program-Footnote-3840009
+Node: Anagram Program840124
+Node: Signature Program843186
+Node: Programs Summary844433
+Node: Programs Exercises845647
+Ref: Programs Exercises-Footnote-1849777
+Node: Advanced Features849863
+Node: Nondecimal Data851994
+Node: Boolean Typed Values853592
+Node: Array Sorting855473
+Node: Controlling Array Traversal856178
+Ref: Controlling Array Traversal-Footnote-1864546
+Node: Array Sorting Functions864664
+Ref: Array Sorting Functions-Footnote-1870038
+Node: Two-way I/O870234
+Ref: Two-way I/O-Footnote-1877960
+Ref: Two-way I/O-Footnote-2878147
+Node: TCP/IP Networking878229
+Node: Profiling881347
+Node: Extension Philosophy890656
+Node: Advanced Features Summary892135
+Node: Internationalization894150
+Node: I18N and L10N895824
+Node: Explaining gettext896511
+Ref: Explaining gettext-Footnote-1902403
+Ref: Explaining gettext-Footnote-2902588
+Node: Programmer i18n902753
+Ref: Programmer i18n-Footnote-1907702
+Node: Translator i18n907751
+Node: String Extraction908545
+Ref: String Extraction-Footnote-1909677
+Node: Printf Ordering909763
+Ref: Printf Ordering-Footnote-1912549
+Node: I18N Portability912613
+Ref: I18N Portability-Footnote-1915069
+Node: I18N Example915132
+Ref: I18N Example-Footnote-1918407
+Ref: I18N Example-Footnote-2918480
+Node: Gawk I18N918589
+Node: I18N Summary919238
+Node: Debugger920579
+Node: Debugging921579
+Node: Debugging Concepts922020
+Node: Debugging Terms923829
+Node: Awk Debugging926404
+Ref: Awk Debugging-Footnote-1927349
+Node: Sample Debugging Session927481
+Node: Debugger Invocation928015
+Node: Finding The Bug929401
+Node: List of Debugger Commands935875
+Node: Breakpoint Control937208
+Node: Debugger Execution Control940902
+Node: Viewing And Changing Data944264
+Node: Execution Stack947805
+Node: Debugger Info949442
+Node: Miscellaneous Debugger Commands953513
+Node: Readline Support958575
+Node: Limitations959471
+Node: Debugging Summary962025
+Node: Namespaces963304
+Node: Global Namespace964415
+Node: Qualified Names965813
+Node: Default Namespace966812
+Node: Changing The Namespace967553
+Node: Naming Rules969167
+Node: Internal Name Management971015
+Node: Namespace Example972057
+Node: Namespace And Features974619
+Node: Namespace Summary976054
+Node: Arbitrary Precision Arithmetic977531
+Node: Computer Arithmetic979018
+Ref: table-numeric-ranges982784
+Ref: table-floating-point-ranges983277
+Ref: Computer Arithmetic-Footnote-1983935
+Node: Math Definitions983992
+Ref: table-ieee-formats986968
+Node: MPFR features987535
+Node: FP Math Caution989253
+Ref: FP Math Caution-Footnote-1990325
+Node: Inexactness of computations990694
+Node: Inexact representation991725
+Node: Comparing FP Values993085
+Node: Errors accumulate994326
+Node: Strange values995782
+Ref: Strange values-Footnote-1998370
+Node: Getting Accuracy998475
+Node: Try To Round1001185
+Node: Setting precision1002084
+Ref: table-predefined-precision-strings1002781
+Node: Setting the rounding mode1004611
+Ref: table-gawk-rounding-modes1004985
+Ref: Setting the rounding mode-Footnote-11008916
+Node: Arbitrary Precision Integers1009095
+Ref: Arbitrary Precision Integers-Footnote-11012270
+Node: Checking for MPFR1012419
+Node: POSIX Floating Point Problems1013893
+Ref: POSIX Floating Point Problems-Footnote-11018178
+Node: Floating point summary1018216
+Node: Dynamic Extensions1020406
+Node: Extension Intro1021959
+Node: Plugin License1023225
+Node: Extension Mechanism Outline1024022
+Ref: figure-load-extension1024461
+Ref: figure-register-new-function1026026
+Ref: figure-call-new-function1027118
+Node: Extension API Description1029180
+Node: Extension API Functions Introduction1030893
+Ref: table-api-std-headers1032729
+Node: General Data Types1036978
+Ref: General Data Types-Footnote-11045684
+Node: Memory Allocation Functions1045983
+Ref: Memory Allocation Functions-Footnote-11050484
+Node: Constructor Functions1050583
+Node: API Ownership of MPFR and GMP Values1054236
+Node: Registration Functions1055549
+Node: Extension Functions1056249
+Node: Exit Callback Functions1061571
+Node: Extension Version String1062821
+Node: Input Parsers1063484
+Node: Output Wrappers1076205
+Node: Two-way processors1080717
+Node: Printing Messages1082982
+Ref: Printing Messages-Footnote-11084153
+Node: Updating ERRNO1084306
+Node: Requesting Values1085045
+Ref: table-value-types-returned1085782
+Node: Accessing Parameters1086890
+Node: Symbol Table Access1088127
+Node: Symbol table by name1088639
+Ref: Symbol table by name-Footnote-11091663
+Node: Symbol table by cookie1091791
+Ref: Symbol table by cookie-Footnote-11095976
+Node: Cached values1096040
+Ref: Cached values-Footnote-11099576
+Node: Array Manipulation1099729
+Ref: Array Manipulation-Footnote-11100820
+Node: Array Data Types1100857
+Ref: Array Data Types-Footnote-11103515
+Node: Array Functions1103607
+Node: Flattening Arrays1108105
+Node: Creating Arrays1115081
+Node: Redirection API1119848
+Node: Extension API Variables1122681
+Node: Extension Versioning1123392
+Ref: gawk-api-version1123821
+Node: Extension GMP/MPFR Versioning1125552
+Node: Extension API Informational Variables1127180
+Node: Extension API Boilerplate1128253
+Node: Changes from API V11132227
+Node: Finding Extensions1133799
+Node: Extension Example1134358
+Node: Internal File Description1135156
+Node: Internal File Ops1139236
+Ref: Internal File Ops-Footnote-11150586
+Node: Using Internal File Ops1150726
+Ref: Using Internal File Ops-Footnote-11153109
+Node: Extension Samples1153383
+Node: Extension Sample File Functions1154912
+Node: Extension Sample Fnmatch1162561
+Node: Extension Sample Fork1164048
+Node: Extension Sample Inplace1165266
+Node: Extension Sample Ord1168892
+Node: Extension Sample Readdir1169728
+Ref: table-readdir-file-types1170617
+Node: Extension Sample Revout1171684
+Node: Extension Sample Rev2way1172273
+Node: Extension Sample Read write array1173013
+Node: Extension Sample Readfile1174955
+Node: Extension Sample Time1176050
+Node: Extension Sample API Tests1177802
+Node: gawkextlib1178294
+Node: Extension summary1181212
+Node: Extension Exercises1184914
+Node: Language History1186156
+Node: V7/SVR3.11187812
+Node: SVR41189964
+Node: POSIX1191398
+Node: BTL1192779
+Node: POSIX/GNU1193508
+Node: Feature History1199286
+Node: Common Extensions1216461
+Node: Ranges and Locales1217744
+Ref: Ranges and Locales-Footnote-11222360
+Ref: Ranges and Locales-Footnote-21222387
+Ref: Ranges and Locales-Footnote-31222622
+Node: Contributors1222845
+Node: History summary1228842
+Node: Installation1230222
+Node: Gawk Distribution1231166
+Node: Getting1231650
+Node: Extracting1232613
+Node: Distribution contents1234251
+Node: Unix Installation1240731
+Node: Quick Installation1241413
+Node: Compiling with MPFR1243894
+Node: Shell Startup Files1244586
+Node: Additional Configuration Options1245675
+Node: Configuration Philosophy1247990
+Node: Non-Unix Installation1250359
+Node: PC Installation1250819
+Node: PC Binary Installation1251657
+Node: PC Compiling1252092
+Node: PC Using1253209
+Node: Cygwin1256762
+Node: MSYS1257986
+Node: VMS Installation1258588
+Node: VMS Compilation1259379
+Ref: VMS Compilation-Footnote-11260608
+Node: VMS Dynamic Extensions1260666
+Node: VMS Installation Details1262351
+Node: VMS Running1264604
+Node: VMS GNV1268883
+Node: VMS Old Gawk1269618
+Node: Bugs1270089
+Node: Bug definition1270969
+Node: Bug address1273473
+Node: Usenet1276861
+Node: Performance bugs1277870
+Node: Asking for help1280791
+Node: Maintainers1282753
+Node: Other Versions1283947
+Node: Installation summary1291799
+Node: Notes1293163
+Node: Compatibility Mode1293957
+Node: Additions1294739
+Node: Accessing The Source1295664
+Node: Adding Code1297101
+Node: New Ports1303320
+Node: Derived Files1307695
+Ref: Derived Files-Footnote-11313355
+Ref: Derived Files-Footnote-21313390
+Ref: Derived Files-Footnote-31313988
+Node: Future Extensions1314102
+Node: Implementation Limitations1314760
+Node: Extension Design1315970
+Node: Old Extension Problems1317114
+Ref: Old Extension Problems-Footnote-11318632
+Node: Extension New Mechanism Goals1318689
+Ref: Extension New Mechanism Goals-Footnote-11322053
+Node: Extension Other Design Decisions1322242
+Node: Extension Future Growth1324355
+Node: Notes summary1324961
+Node: Basic Concepts1326119
+Node: Basic High Level1326800
+Ref: figure-general-flow1327082
+Ref: figure-process-flow1327767
+Ref: Basic High Level-Footnote-11331068
+Node: Basic Data Typing1331253
+Node: Glossary1334581
+Node: Copying1366468
+Node: GNU Free Documentation License1404011
+Node: Index1429131
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 945e7670..206b4c1e 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
 
@@ -1061,9 +1061,11 @@ particular records in a file and perform operations upon them.
 * VMS Old Gawk::                        An old version comes with some VMS
                                         systems.
 * Bugs::                                Reporting Problems and Bugs.
+* Bug definition::                      Defining what is and is not a bug.
 * Bug address::                         Where to send reports to.
 * Usenet::                              Where not to send reports to.
 * Performance bugs::                    What to do if you think there is a performance issue.
+* Asking for help::                     Dealing with non-bug questions.
 * Maintainers::                         Maintainers of non-*nix ports.
 * Other Versions::                      Other freely available @command{awk}
                                         implementations.
@@ -18694,6 +18696,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
@@ -29962,6 +29967,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
@@ -43120,38 +43131,157 @@ report it to the developers; we cannot promise to do anything,
 but we might well want to fix it.
 
 @menu
+* Bug definition::              Defining what is and is not a bug.
 * Bug address::                 Where to send reports to.
 * Usenet::                      Where not to send reports to.
 * Performance bugs::            What to do if you think there is a performance issue.
+* Asking for help::             Dealing with non-bug questions.
 * Maintainers::                 Maintainers of non-*nix ports.
 @end menu
 
+@node Bug definition
+@appendixsubsec Defining What Is and What Is Not A Bug
+
+Before talking about reporting bugs, let's define what is a bug,
+and what is not.
+
+A bug is:
+
+@itemize @bullet
+@item
+When @command{gawk} behaves differently from what's described
+in the POSIX standard, and that difference is not mentioned
+in this @value{DOCUMENT} as being done on purpose.
+
+@item
+When @command{gawk} behaves differently from what's described
+in this @value{DOCUMENT}.
+
+@item
+When @command{gawk} behaves differently from other @command{awk}
+implementations in particular circumstances, and that behavior cannot
+be attributed to an additional feature in @command{gawk}.
+
+@item
+Something that is obviously wrong, such as a core dump.
+
+@item
+When this @value{DOCUMENT} is unclear or ambiguous about a particular
+feature's behavior.
+@end itemize
+
+The following things are @emph{not} bugs, and should not be reported
+to the bug mailing list.  You can ask about them on the ``help'' mailing
+list (@pxref{Asking for help}), but don't be surprised if you get an
+answer of the form ``that's how @command{gawk} behaves and it isn't
+going to change.''
+
+@itemize @bullet
+@item
+Missing features, for any definition of @dfn{feature}. For example,
+additional built-in arithmetic functions, or additional ways to split
+fields or records, or anything else.
+
+The number of features that @command{gawk} does @emph{not} have is
+by definition infinite.  It cannot be all things to all people.
+
+@item
+Behaviors that are defined by the POSIX standard and/or for historical
+compatibility with Unix @command{awk}.  Even if you happen to dislike
+those behaviors, they're not going to change: changing them would
+break millions of existing @command{awk} programs.
+
+@item
+Behaviors that differ from how it's done in other languages. @command{awk}
+and @command{gawk} stand on their own and do not have to follow the crowd.
+This is particularly true when the requested behavior change would break
+backwards compatibility.
+
+@item
+Documentation issues of the form ``the manual doesn't tell me how to
+do XYZ.''  The manual is not a cookbook to solve every little problem
+you may have.
+
+@item
+General questions and discussion about @command{awk} programming or
+why @command{gawk} behaves the way it does. For that use the ``help''
+mailing list: see @ref{Asking for help}.
+@end itemize
+
+For more information, see @uref{http://www.skeeve.com/fork-my-code.html,
+@cite{Fork My Code, Please!---An Open Letter To Those of You Who Are Unhappy}},
+by Arnold Robbins and Chet Ramey.
+
 @node Bug address
 @appendixsubsec Submitting Bug Reports
 
 Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of @command{gawk}.
+
+Here are the steps for submitting a bug report. Following them will
+make both your life and the lives of the maintainers much easier.
+
+@enumerate 1
+@item
+Make sure that what you want to report is appropriate.
+@xref{Bug definition}.  If it's not, you are wasting your
+time and ours.
+
+@item
+Verify that you have the latest version of @command{gawk}.
 Many bugs (usually subtle ones) are fixed at each release, and if yours
 is out of date, the problem may already have been solved.
 
-Second, please see if setting the environment variable @env{LC_ALL}
+@item
+Please see if setting the environment variable @env{LC_ALL}
 to @code{LC_ALL=C} causes things to behave as you expect. If so, it's
 a locale issue, and may or may not really be a bug.
 
-Third, carefully reread the documentation and see if it says you can do
+@item
+Carefully reread the documentation and see if it says you can do
 what you're trying to do.  If it's not clear whether you should be able
 to do something or not, report that too; it's a bug in the documentation!
 
-Finally, before reporting a bug or trying to fix it yourself, try to isolate it
+@item
+Before reporting a bug or trying to fix it yourself, try to isolate it
 to the smallest possible @command{awk} program and input @value{DF} that
-reproduce the problem.  Then send us the program and @value{DF},
-some idea of what kind of Unix system you're using,
-the compiler you used to compile @command{gawk}, and the exact results
+reproduce the problem.  Then send us:
+
+@itemize @bullet
+@item
+The program and @value{DF}.
+
+@item
+Some idea of what kind of Unix system you're using.
+
+@item
+The compiler you used to compile @command{gawk}.
+
+@item
+The exact results
 @command{gawk} gave you.  Also say what you expected to occur; this helps
 us decide whether the problem is really in the documentation.
 
-Make sure to include the version number of @command{gawk} you are using.
+@item
+The version number of @command{gawk} you are using.
 You can get this information with the command @samp{gawk --version}.
+@end itemize
+
+@item
+Do @emph{not} send screenshots. Instead, use copy/paste to send text, or
+send files.
+
+@item
+Do send files as attachments, instead of inline. This avoids corruption
+by mailer programs out in the wilds of the Internet.
+
+@item
+Please be sure to send all mail in @emph{plain text},
+not (or not exclusively) in HTML.
+
+@item
+@emph{All email must be in English. This is the only language
+understood in common by all the maintainers.}
+@end enumerate
 
 @cindex @code{bug-gawk@@gnu.org} bug reporting address
 @cindex email address for bug reports, @code{bug-gawk@@gnu.org}
@@ -43164,10 +43294,6 @@ thus they will receive your bug report.
 Although you can send mail to the maintainers directly,
 the bug reporting address is preferred because the
 email list is archived at the GNU Project.
-@emph{All email must be in English. This is the only language
-understood in common by all the maintainers.}
-In addition, please be sure to send all mail in @emph{plain text},
-not (or not exclusively) in HTML.
 
 @quotation NOTE
 Many distributions of GNU/Linux and the various BSD-based operating systems
@@ -43182,10 +43308,6 @@ mail to the GNU list is archived, and having everything at the GNU Project
 keeps things self-contained and not dependent on other organizations.
 @end quotation
 
-Non-bug suggestions are always welcome as well.  If you have questions
-about things that are unclear in the documentation or are just obscure
-features, ask on the bug list; we will try to help you out if we can.
-
 Please note: We ask that you follow the
 @uref{https://gnu.org/philosophy/kind-communication.html,
 GNU Kind Communication Guidelines} in your correspondence on the
@@ -43263,10 +43385,10 @@ it:
 
 @example
 $ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 $ @kbd{cd gawk-X.Y.Z}
 $ @kbd{./configure}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 @end example
 
 @item
@@ -43280,7 +43402,7 @@ Compile the program by running the @command{make} command:
 @example
 @group
 $ @kbd{make}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 @end group
 @end example
 
@@ -43294,6 +43416,10 @@ that something is slow, it @emph{must} be done using a real program and real dat
 Use a data file that is large enough for the statistical profiling to measure
 where @command{gawk} spends its time. It should be at least 100 megabytes in size.
 
+@example
+$ @kbd{./gawk -f realprogram.awk realdata > /dev/null}
+@end example
+
 @item
 When done, you should have a file in the current directory named @file{gmon.out}.
 Run the command @samp{gprof gawk gmon.out > gprof.out}.
@@ -43314,6 +43440,65 @@ rerun the profiling in order to see if the patches were effective.
 If you are incapable or unwilling to do the steps listed above, then you will
 just have to live with @command{gawk} as it is.
 
+@node Asking for help
+@appendixsubsec Where To Send Non-bug Questions
+
+If you have questions related to @command{awk} programming, or why @command{gawk}
+behaves a certain way, or any other @command{awk}- or @command{gawk}-related issue,
+please @emph{do not} send it to the bug reporting address.
+
+As of July, 2021, there is a separate mailing list for this purpose:
+@EMAIL{help-gawk@@gnu.org, help-gawk at gnu.org}.
+Anything that is not a bug report should be sent to that list.
+
+@quotation NOTE
+If you disregard these directions and send non-bug mails to the bug list,
+you will be told to use the help list.
+After two such requests you will be silently @emph{blacklisted} from the bug list.
+@end quotation
+
+Please note: As with the bug list, we ask that you follow the
+@uref{https://gnu.org/philosophy/kind-communication.html,
+GNU Kind Communication Guidelines} in your correspondence on the
+list (as well as off of it).
+
+If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy
+of Bob Proulx:
+
+
+@table @emph
+@item Subscribe by email
+
+Send an email message to
+@EMAIL{help-gawk-request@@gnu.org, help-gawk-request AT gnu.org}
+with ``subscribe'' in
+the body of the message.  The subject does not matter and is not used.
+
+@item Subscribe by web form
+
+To use the web interface visit
+@uref{https://lists.gnu.org/mailman/listinfo/help-gawk,
+the list information page}.
+Use the
+subscribe form to fill out your email address and submit using the
+@code{Subscribe} button.
+
+@item Reply to the confirmation message
+
+In both cases then reply to the confirmation message that is sent to
+your address in reply.
+@end table
+
+Bob mentions that you may also use email for subscribing and
+unsubscribing. For example:
+
+@example
+$ @kbd{echo help | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo subscribe | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo unsubscribe | mailx -s request help-gawk-request@@gnu.org}
+@end example
+
 @node Maintainers
 @appendixsubsec Reporting Problems with Non-Unix Ports
 
@@ -43464,8 +43649,7 @@ and links them with a library of functions that provide the core
 @command{awk} functionality.
 It also has a number of extensions.
 
-The @command{awk} translator is released under the GPL, and the library
-is under the LGPL.
+Both the @command{awk} translator and the library are released under the GPL.
 
 To get @command{awka}, go to @url{https://sourceforge.net/projects/awka}.
 @c You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
@@ -43642,12 +43826,16 @@ and both Vax/VMS and OpenVMS.
 Instructions for each system are included in this @value{APPENDIX}.
 
 @item
-Bug reports should be sent via email to @email{bug-gawk@@gnu.org}.
+Bug reports should be sent via email to @EMAIL{bug-gawk@@gnu.org, bug-gawk AT gnu.org}.
 Bug reports should be in English and should include the version of @command{gawk},
 how it was compiled, and a short program and @value{DF} that demonstrate
 the problem.
 
 @item
+Non-bug emails should be sent to @EMAIL{help-gawk@@gnu.org, help-gawk AT gnu.org}.
+Repeatedly sending non-bug emails to the bug list will get you blacklisted from it.
+
+@item
 There are a number of other freely available @command{awk}
 implementations.  Many are POSIX-compliant; others are less so.
 
@@ -43960,7 +44148,7 @@ your code in the public domain and submit a signed statement to that
 effect, or assign the copyright in your code to the FSF.
 Both of these actions are easy to do and @emph{many} people have done so
 already. If you have questions, please contact me, or
-@email{gnu@@gnu.org}.
+@EMAIL{gnu@@gnu.org, gnu AT gnu.org}.
 
 @item
 When doing a port, bear in mind that your code must coexist peacefully
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index b64c192a..557df443 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
 
@@ -1056,9 +1056,11 @@ particular records in a file and perform operations upon them.
 * VMS Old Gawk::                        An old version comes with some VMS
                                         systems.
 * Bugs::                                Reporting Problems and Bugs.
+* Bug definition::                      Defining what is and is not a bug.
 * Bug address::                         Where to send reports to.
 * Usenet::                              Where not to send reports to.
 * Performance bugs::                    What to do if you think there is a performance issue.
+* Asking for help::                     Dealing with non-bug questions.
 * Maintainers::                         Maintainers of non-*nix ports.
 * Other Versions::                      Other freely available @command{awk}
                                         implementations.
@@ -17835,6 +17837,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
@@ -28844,6 +28849,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
@@ -41963,38 +41974,157 @@ report it to the developers; we cannot promise to do anything,
 but we might well want to fix it.
 
 @menu
+* Bug definition::              Defining what is and is not a bug.
 * Bug address::                 Where to send reports to.
 * Usenet::                      Where not to send reports to.
 * Performance bugs::            What to do if you think there is a performance issue.
+* Asking for help::             Dealing with non-bug questions.
 * Maintainers::                 Maintainers of non-*nix ports.
 @end menu
 
+@node Bug definition
+@appendixsubsec Defining What Is and What Is Not A Bug
+
+Before talking about reporting bugs, let's define what is a bug,
+and what is not.
+
+A bug is:
+
+@itemize @bullet
+@item
+When @command{gawk} behaves differently from what's described
+in the POSIX standard, and that difference is not mentioned
+in this @value{DOCUMENT} as being done on purpose.
+
+@item
+When @command{gawk} behaves differently from what's described
+in this @value{DOCUMENT}.
+
+@item
+When @command{gawk} behaves differently from other @command{awk}
+implementations in particular circumstances, and that behavior cannot
+be attributed to an additional feature in @command{gawk}.
+
+@item
+Something that is obviously wrong, such as a core dump.
+
+@item
+When this @value{DOCUMENT} is unclear or ambiguous about a particular
+feature's behavior.
+@end itemize
+
+The following things are @emph{not} bugs, and should not be reported
+to the bug mailing list.  You can ask about them on the ``help'' mailing
+list (@pxref{Asking for help}), but don't be surprised if you get an
+answer of the form ``that's how @command{gawk} behaves and it isn't
+going to change.''
+
+@itemize @bullet
+@item
+Missing features, for any definition of @dfn{feature}. For example,
+additional built-in arithmetic functions, or additional ways to split
+fields or records, or anything else.
+
+The number of features that @command{gawk} does @emph{not} have is
+by definition infinite.  It cannot be all things to all people.
+
+@item
+Behaviors that are defined by the POSIX standard and/or for historical
+compatibility with Unix @command{awk}.  Even if you happen to dislike
+those behaviors, they're not going to change: changing them would
+break millions of existing @command{awk} programs.
+
+@item
+Behaviors that differ from how it's done in other languages. @command{awk}
+and @command{gawk} stand on their own and do not have to follow the crowd.
+This is particularly true when the requested behavior change would break
+backwards compatibility.
+
+@item
+Documentation issues of the form ``the manual doesn't tell me how to
+do XYZ.''  The manual is not a cookbook to solve every little problem
+you may have.
+
+@item
+General questions and discussion about @command{awk} programming or
+why @command{gawk} behaves the way it does. For that use the ``help''
+mailing list: see @ref{Asking for help}.
+@end itemize
+
+For more information, see @uref{http://www.skeeve.com/fork-my-code.html,
+@cite{Fork My Code, Please!---An Open Letter To Those of You Who Are Unhappy}},
+by Arnold Robbins and Chet Ramey.
+
 @node Bug address
 @appendixsubsec Submitting Bug Reports
 
 Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of @command{gawk}.
+
+Here are the steps for submitting a bug report. Following them will
+make both your life and the lives of the maintainers much easier.
+
+@enumerate 1
+@item
+Make sure that what you want to report is appropriate.
+@xref{Bug definition}.  If it's not, you are wasting your
+time and ours.
+
+@item
+Verify that you have the latest version of @command{gawk}.
 Many bugs (usually subtle ones) are fixed at each release, and if yours
 is out of date, the problem may already have been solved.
 
-Second, please see if setting the environment variable @env{LC_ALL}
+@item
+Please see if setting the environment variable @env{LC_ALL}
 to @code{LC_ALL=C} causes things to behave as you expect. If so, it's
 a locale issue, and may or may not really be a bug.
 
-Third, carefully reread the documentation and see if it says you can do
+@item
+Carefully reread the documentation and see if it says you can do
 what you're trying to do.  If it's not clear whether you should be able
 to do something or not, report that too; it's a bug in the documentation!
 
-Finally, before reporting a bug or trying to fix it yourself, try to isolate it
+@item
+Before reporting a bug or trying to fix it yourself, try to isolate it
 to the smallest possible @command{awk} program and input @value{DF} that
-reproduce the problem.  Then send us the program and @value{DF},
-some idea of what kind of Unix system you're using,
-the compiler you used to compile @command{gawk}, and the exact results
+reproduce the problem.  Then send us:
+
+@itemize @bullet
+@item
+The program and @value{DF}.
+
+@item
+Some idea of what kind of Unix system you're using.
+
+@item
+The compiler you used to compile @command{gawk}.
+
+@item
+The exact results
 @command{gawk} gave you.  Also say what you expected to occur; this helps
 us decide whether the problem is really in the documentation.
 
-Make sure to include the version number of @command{gawk} you are using.
+@item
+The version number of @command{gawk} you are using.
 You can get this information with the command @samp{gawk --version}.
+@end itemize
+
+@item
+Do @emph{not} send screenshots. Instead, use copy/paste to send text, or
+send files.
+
+@item
+Do send files as attachments, instead of inline. This avoids corruption
+by mailer programs out in the wilds of the Internet.
+
+@item
+Please be sure to send all mail in @emph{plain text},
+not (or not exclusively) in HTML.
+
+@item
+@emph{All email must be in English. This is the only language
+understood in common by all the maintainers.}
+@end enumerate
 
 @cindex @code{bug-gawk@@gnu.org} bug reporting address
 @cindex email address for bug reports, @code{bug-gawk@@gnu.org}
@@ -42007,10 +42137,6 @@ thus they will receive your bug report.
 Although you can send mail to the maintainers directly,
 the bug reporting address is preferred because the
 email list is archived at the GNU Project.
-@emph{All email must be in English. This is the only language
-understood in common by all the maintainers.}
-In addition, please be sure to send all mail in @emph{plain text},
-not (or not exclusively) in HTML.
 
 @quotation NOTE
 Many distributions of GNU/Linux and the various BSD-based operating systems
@@ -42025,10 +42151,6 @@ mail to the GNU list is archived, and having everything at the GNU Project
 keeps things self-contained and not dependent on other organizations.
 @end quotation
 
-Non-bug suggestions are always welcome as well.  If you have questions
-about things that are unclear in the documentation or are just obscure
-features, ask on the bug list; we will try to help you out if we can.
-
 Please note: We ask that you follow the
 @uref{https://gnu.org/philosophy/kind-communication.html,
 GNU Kind Communication Guidelines} in your correspondence on the
@@ -42106,10 +42228,10 @@ it:
 
 @example
 $ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 $ @kbd{cd gawk-X.Y.Z}
 $ @kbd{./configure}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 @end example
 
 @item
@@ -42123,7 +42245,7 @@ Compile the program by running the @command{make} command:
 @example
 @group
 $ @kbd{make}
-@print{} @dots{}                                @ii{Output ommited}
+@print{} @dots{}                                @ii{Output omitted}
 @end group
 @end example
 
@@ -42137,6 +42259,10 @@ that something is slow, it @emph{must} be done using a real program and real dat
 Use a data file that is large enough for the statistical profiling to measure
 where @command{gawk} spends its time. It should be at least 100 megabytes in size.
 
+@example
+$ @kbd{./gawk -f realprogram.awk realdata > /dev/null}
+@end example
+
 @item
 When done, you should have a file in the current directory named @file{gmon.out}.
 Run the command @samp{gprof gawk gmon.out > gprof.out}.
@@ -42157,6 +42283,65 @@ rerun the profiling in order to see if the patches were effective.
 If you are incapable or unwilling to do the steps listed above, then you will
 just have to live with @command{gawk} as it is.
 
+@node Asking for help
+@appendixsubsec Where To Send Non-bug Questions
+
+If you have questions related to @command{awk} programming, or why @command{gawk}
+behaves a certain way, or any other @command{awk}- or @command{gawk}-related issue,
+please @emph{do not} send it to the bug reporting address.
+
+As of July, 2021, there is a separate mailing list for this purpose:
+@EMAIL{help-gawk@@gnu.org, help-gawk at gnu.org}.
+Anything that is not a bug report should be sent to that list.
+
+@quotation NOTE
+If you disregard these directions and send non-bug mails to the bug list,
+you will be told to use the help list.
+After two such requests you will be silently @emph{blacklisted} from the bug list.
+@end quotation
+
+Please note: As with the bug list, we ask that you follow the
+@uref{https://gnu.org/philosophy/kind-communication.html,
+GNU Kind Communication Guidelines} in your correspondence on the
+list (as well as off of it).
+
+If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy
+of Bob Proulx:
+
+
+@table @emph
+@item Subscribe by email
+
+Send an email message to
+@EMAIL{help-gawk-request@@gnu.org, help-gawk-request AT gnu.org}
+with ``subscribe'' in
+the body of the message.  The subject does not matter and is not used.
+
+@item Subscribe by web form
+
+To use the web interface visit
+@uref{https://lists.gnu.org/mailman/listinfo/help-gawk,
+the list information page}.
+Use the
+subscribe form to fill out your email address and submit using the
+@code{Subscribe} button.
+
+@item Reply to the confirmation message
+
+In both cases then reply to the confirmation message that is sent to
+your address in reply.
+@end table
+
+Bob mentions that you may also use email for subscribing and
+unsubscribing. For example:
+
+@example
+$ @kbd{echo help | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo subscribe | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo unsubscribe | mailx -s request help-gawk-request@@gnu.org}
+@end example
+
 @node Maintainers
 @appendixsubsec Reporting Problems with Non-Unix Ports
 
@@ -42307,8 +42492,7 @@ and links them with a library of functions that provide the core
 @command{awk} functionality.
 It also has a number of extensions.
 
-The @command{awk} translator is released under the GPL, and the library
-is under the LGPL.
+Both the @command{awk} translator and the library are released under the GPL.
 
 To get @command{awka}, go to @url{https://sourceforge.net/projects/awka}.
 @c You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
@@ -42485,12 +42669,16 @@ and both Vax/VMS and OpenVMS.
 Instructions for each system are included in this @value{APPENDIX}.
 
 @item
-Bug reports should be sent via email to @email{bug-gawk@@gnu.org}.
+Bug reports should be sent via email to @EMAIL{bug-gawk@@gnu.org, bug-gawk AT gnu.org}.
 Bug reports should be in English and should include the version of @command{gawk},
 how it was compiled, and a short program and @value{DF} that demonstrate
 the problem.
 
 @item
+Non-bug emails should be sent to @EMAIL{help-gawk@@gnu.org, help-gawk AT gnu.org}.
+Repeatedly sending non-bug emails to the bug list will get you blacklisted from it.
+
+@item
 There are a number of other freely available @command{awk}
 implementations.  Many are POSIX-compliant; others are less so.
 
@@ -42803,7 +42991,7 @@ your code in the public domain and submit a signed statement to that
 effect, or assign the copyright in your code to the FSF.
 Both of these actions are easy to do and @emph{many} people have done so
 already. If you have questions, please contact me, or
-@email{gnu@@gnu.org}.
+@EMAIL{gnu@@gnu.org, gnu AT gnu.org}.
 
 @item
 When doing a port, bear in mind that your code must coexist peacefully