Merge branch 'gawk-5.1-stable'

4 files changed, 508 insertions, 452 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index dffb7a96..95f27d75 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,11 @@
+2021-10-09         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Clarify that initialization and increment parts of
+	a for loop can't use the C comma operator.  Thanks to J Naman
+	<jnaman2@gmail.com> for pointing out the doc was too subtle.
+	Unrelated: further expand the bug reporting text and discussion
+	about comp.lang.awk.
+
 2021-10-03         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Continue clarifying typeof() usage. And other fixes.
diff --git a/doc/gawk.info b/doc/gawk.info
index 862860d2..c1c4080c 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -10584,18 +10584,21 @@ desired number of iterations.  For example:
 This prints the first three fields of each input record, with one input
 field per output line.
 
-   It isn't possible to set more than one variable in the INITIALIZATION
-part without using a multiple assignment statement such as 'x = y = 0'.
-This makes sense only if all the initial values are equal.  (But it is
-possible to initialize additional variables by writing their assignments
-as separate statements preceding the 'for' loop.)
-
-   The same is true of the INCREMENT part.  Incrementing additional
-variables requires separate statements at the end of the loop.  The C
-compound expression, using C's comma operator, is useful in this
-context, but it is not supported in 'awk'.
-
-   Most often, INCREMENT is an increment expression, as in the previous
+   C and C++ programmers might expect to be able to use the comma
+operator to set more than one variable in the INITIALIZATION part of the
+'for' loop, or to increment multiple variables in the INCREMEMNT part of
+the loop, like so:
+
+     for (i = 0, j = length(a); i < j; i++, j--) ...   C/C++, not awk!
+
+You cannot do this; the comma operator is not supported in 'awk'.  There
+are workarounds, but they are nonobvious and can lead to code that is
+difficult to read and understand.  It is best, therefore, to simply
+write additional initializations as separate statements preceding the
+'for' loop and to place additional increment statements at the end of
+the loop's body.
+
+   Most often, INCREMENT is an increment expression, as in the earlier
 example.  But this is not required; it can be any expression whatsoever.
 For example, the following statement prints all the powers of two
 between 1 and 100:
@@ -31695,13 +31698,16 @@ what is not.
 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."
+Here's the list:
 
    * 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.
+     infinite.  It cannot be all things to all people.  In short, just
+     because 'gawk' doesn't do what _you_ think it should, it's not
+     necessarily a bug.
 
    * Behaviors that are defined by the POSIX standard and/or for
      historical compatibility with Unix 'awk'.  Even if you happen to
@@ -31713,9 +31719,15 @@ of the form "that's how 'gawk' behaves and it isn't going to change."
      This is particularly true when the requested behavior change would
      break backwards compatibility.
 
+     This applies also to differences in behavior between 'gawk' and
+     other language compilers and interpreters, such as wishes for more
+     detailed descriptions of what the problem is when a syntax error is
+     encountered.
+
    * 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.
+     you may have.  Its purpose is to teach you how to solve your
+     problems on your own.
 
    * General questions and discussion about 'awk' programming or why
      'gawk' behaves the way it does.  For that use the "help" mailing
@@ -31741,7 +31753,7 @@ make both your life and the lives of the maintainers much easier.
 
   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.
+     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
@@ -31822,6 +31834,10 @@ developers occasionally read this news group, the primary 'gawk'
 maintainer no longer does.  Thus it's virtually guaranteed that he will
 _not_ see your posting.
 
+   If you really don't care about the previous paragraph and continue to
+post bug reports in 'comp.lang.awk', then understand that you're not
+reporting bugs, you're just whining.
+
    Similarly, posting bug reports or questions in web forums (such as
 Stack Overflow (https://stackoverflow.com/)) may get you an answer, but
 it won't be from the 'gawk' maintainers, who do not spend their time in
@@ -31917,7 +31933,7 @@ to that 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).
+correspondence on the help 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
@@ -37135,7 +37151,7 @@ Index
 * in operator:                           Comparison Operators.
                                                               (line  11)
 * in operator <1>:                       Precedence.          (line  82)
-* in operator <2>:                       For Statement.       (line  75)
+* in operator <2>:                       For Statement.       (line  78)
 * in operator, testing if array element exists: Reference to Elements.
                                                               (line  38)
 * in operator, use in loops:             Scanning an Array.   (line  17)
@@ -37355,7 +37371,7 @@ Index
 * loops, while:                          While Statement.     (line   6)
 * loops, do-while:                       Do Statement.        (line   6)
 * loops, for, iterative:                 For Statement.       (line   6)
-* loops, continue statement and:         For Statement.       (line  64)
+* loops, continue statement and:         For Statement.       (line  67)
 * loops, exiting:                        Break Statement.     (line   6)
 * loops, break statement and:            Break Statement.     (line   6)
 * loops, for, array scanning:            Scanning an Array.   (line   6)
@@ -38839,406 +38855,406 @@ Node: If Statement448734
 Node: While Statement450229
 Node: Do Statement452257
 Node: For Statement453405
-Node: Switch Statement456576
-Node: Break Statement459017
-Node: Continue Statement461109
-Node: Next Statement462936
-Node: Nextfile Statement465319
-Node: Exit Statement468008
-Node: Built-in Variables470411
-Node: User-modified471544
-Node: Auto-set479311
-Ref: Auto-set-Footnote-1496118
-Ref: Auto-set-Footnote-2496324
-Node: ARGC and ARGV496380
-Node: Pattern Action Summary500593
-Node: Arrays503023
-Node: Array Basics504352
-Node: Array Intro505196
-Ref: figure-array-elements507171
-Ref: Array Intro-Footnote-1509875
-Node: Reference to Elements510003
-Node: Assigning Elements512467
-Node: Array Example512958
-Node: Scanning an Array514717
-Node: Controlling Scanning517739
-Ref: Controlling Scanning-Footnote-1524195
-Node: Numeric Array Subscripts524511
-Node: Uninitialized Subscripts526695
-Node: Delete528314
-Ref: Delete-Footnote-1531066
-Node: Multidimensional531123
-Node: Multiscanning534218
-Node: Arrays of Arrays535809
-Node: Arrays Summary540577
-Node: Functions542670
-Node: Built-in543708
-Node: Calling Built-in544861
-Node: Boolean Functions546857
-Node: Numeric Functions547411
-Ref: Numeric Functions-Footnote-1551438
-Ref: Numeric Functions-Footnote-2552086
-Ref: Numeric Functions-Footnote-3552134
-Node: String Functions552406
-Ref: String Functions-Footnote-1576921
-Ref: String Functions-Footnote-2577049
-Ref: String Functions-Footnote-3577297
-Node: Gory Details577384
-Ref: table-sub-escapes579175
-Ref: table-sub-proposed580694
-Ref: table-posix-sub582057
-Ref: table-gensub-escapes583598
-Ref: Gory Details-Footnote-1584421
-Node: I/O Functions584575
-Ref: table-system-return-values591029
-Ref: I/O Functions-Footnote-1593109
-Ref: I/O Functions-Footnote-2593257
-Node: Time Functions593377
-Ref: Time Functions-Footnote-1604048
-Ref: Time Functions-Footnote-2604116
-Ref: Time Functions-Footnote-3604274
-Ref: Time Functions-Footnote-4604385
-Ref: Time Functions-Footnote-5604497
-Ref: Time Functions-Footnote-6604724
-Node: Bitwise Functions604990
-Ref: table-bitwise-ops605584
-Ref: Bitwise Functions-Footnote-1611647
-Ref: Bitwise Functions-Footnote-2611820
-Node: Type Functions612011
-Node: I18N Functions615431
-Node: User-defined617082
-Node: Definition Syntax617894
-Ref: Definition Syntax-Footnote-1623588
-Node: Function Example623659
-Ref: Function Example-Footnote-1626581
-Node: Function Calling626603
-Node: Calling A Function627191
-Node: Variable Scope628149
-Node: Pass By Value/Reference631143
-Node: Function Caveats633787
-Ref: Function Caveats-Footnote-1635834
-Node: Return Statement635954
-Node: Dynamic Typing638933
-Node: Indirect Calls639863
-Ref: Indirect Calls-Footnote-1650118
-Node: Functions Summary650246
-Node: Library Functions652951
-Ref: Library Functions-Footnote-1656558
-Ref: Library Functions-Footnote-2656701
-Node: Library Names656872
-Ref: Library Names-Footnote-1660539
-Ref: Library Names-Footnote-2660762
-Node: General Functions660848
-Node: Strtonum Function662030
-Node: Assert Function665052
-Node: Round Function668378
-Node: Cliff Random Function669918
-Node: Ordinal Functions670934
-Ref: Ordinal Functions-Footnote-1673997
-Ref: Ordinal Functions-Footnote-2674249
-Node: Join Function674459
-Ref: Join Function-Footnote-1676229
-Node: Getlocaltime Function676429
-Node: Readfile Function680171
-Node: Shell Quoting682148
-Node: Isnumeric Function683576
-Node: Data File Management684964
-Node: Filetrans Function685596
-Node: Rewind Function689692
-Node: File Checking691601
-Ref: File Checking-Footnote-1692935
-Node: Empty Files693136
-Node: Ignoring Assigns695115
-Node: Getopt Function696665
-Ref: Getopt Function-Footnote-1711888
-Node: Passwd Functions712088
-Ref: Passwd Functions-Footnote-1720927
-Node: Group Functions721015
-Ref: Group Functions-Footnote-1728913
-Node: Walking Arrays729120
-Node: Library Functions Summary732128
-Node: Library Exercises733534
-Node: Sample Programs733999
-Node: Running Examples734769
-Node: Clones735497
-Node: Cut Program736721
-Node: Egrep Program746861
-Node: Id Program755862
-Node: Split Program765809
-Ref: Split Program-Footnote-1775702
-Node: Tee Program775875
-Node: Uniq Program778665
-Node: Wc Program786253
-Node: Bytes vs. Characters786640
-Node: Using extensions788188
-Node: wc program788942
-Node: Miscellaneous Programs793807
-Node: Dupword Program795020
-Node: Alarm Program797050
-Node: Translate Program801905
-Ref: Translate Program-Footnote-1806470
-Node: Labels Program806740
-Ref: Labels Program-Footnote-1810091
-Node: Word Sorting810175
-Node: History Sorting814247
-Node: Extract Program816472
-Node: Simple Sed824526
-Node: Igawk Program827600
-Ref: Igawk Program-Footnote-1841931
-Ref: Igawk Program-Footnote-2842133
-Ref: Igawk Program-Footnote-3842255
-Node: Anagram Program842370
-Node: Signature Program845432
-Node: Programs Summary846679
-Node: Programs Exercises847893
-Ref: Programs Exercises-Footnote-1852023
-Node: Advanced Features852109
-Node: Nondecimal Data854240
-Node: Boolean Typed Values855838
-Node: Array Sorting857719
-Node: Controlling Array Traversal858424
-Ref: Controlling Array Traversal-Footnote-1866792
-Node: Array Sorting Functions866910
-Ref: Array Sorting Functions-Footnote-1872284
-Node: Two-way I/O872480
-Ref: Two-way I/O-Footnote-1880206
-Ref: Two-way I/O-Footnote-2880393
-Node: TCP/IP Networking880475
-Node: Profiling883593
-Node: Extension Philosophy892902
-Node: Advanced Features Summary894381
-Node: Internationalization896396
-Node: I18N and L10N898070
-Node: Explaining gettext898757
-Ref: Explaining gettext-Footnote-1904649
-Ref: Explaining gettext-Footnote-2904834
-Node: Programmer i18n904999
-Ref: Programmer i18n-Footnote-1909948
-Node: Translator i18n909997
-Node: String Extraction910791
-Ref: String Extraction-Footnote-1911923
-Node: Printf Ordering912009
-Ref: Printf Ordering-Footnote-1914795
-Node: I18N Portability914859
-Ref: I18N Portability-Footnote-1917315
-Node: I18N Example917378
-Ref: I18N Example-Footnote-1920653
-Ref: I18N Example-Footnote-2920726
-Node: Gawk I18N920835
-Node: I18N Summary921484
-Node: Debugger922825
-Node: Debugging923825
-Node: Debugging Concepts924266
-Node: Debugging Terms926075
-Node: Awk Debugging928650
-Ref: Awk Debugging-Footnote-1929595
-Node: Sample Debugging Session929727
-Node: Debugger Invocation930261
-Node: Finding The Bug931647
-Node: List of Debugger Commands938121
-Node: Breakpoint Control939454
-Node: Debugger Execution Control943148
-Node: Viewing And Changing Data946510
-Node: Execution Stack950051
-Node: Debugger Info951688
-Node: Miscellaneous Debugger Commands955759
-Node: Readline Support960821
-Node: Limitations961717
-Node: Debugging Summary964271
-Node: Namespaces965550
-Node: Global Namespace966661
-Node: Qualified Names968059
-Node: Default Namespace969058
-Node: Changing The Namespace969799
-Node: Naming Rules971413
-Node: Internal Name Management973261
-Node: Namespace Example974303
-Node: Namespace And Features976865
-Node: Namespace Summary978300
-Node: Arbitrary Precision Arithmetic979777
-Node: Computer Arithmetic981264
-Ref: table-numeric-ranges985030
-Ref: table-floating-point-ranges985523
-Ref: Computer Arithmetic-Footnote-1986181
-Node: Math Definitions986238
-Ref: table-ieee-formats989214
-Node: MPFR features989781
-Node: FP Math Caution991499
-Ref: FP Math Caution-Footnote-1992571
-Node: Inexactness of computations992940
-Node: Inexact representation993971
-Node: Comparing FP Values995331
-Node: Errors accumulate996572
-Node: Strange values998028
-Ref: Strange values-Footnote-11000616
-Node: Getting Accuracy1000721
-Node: Try To Round1003431
-Node: Setting precision1004330
-Ref: table-predefined-precision-strings1005027
-Node: Setting the rounding mode1006857
-Ref: table-gawk-rounding-modes1007231
-Ref: Setting the rounding mode-Footnote-11011162
-Node: Arbitrary Precision Integers1011341
-Ref: Arbitrary Precision Integers-Footnote-11014516
-Node: Checking for MPFR1014665
-Node: POSIX Floating Point Problems1016139
-Ref: POSIX Floating Point Problems-Footnote-11020424
-Node: Floating point summary1020462
-Node: Dynamic Extensions1022652
-Node: Extension Intro1024205
-Node: Plugin License1025471
-Node: Extension Mechanism Outline1026268
-Ref: figure-load-extension1026707
-Ref: figure-register-new-function1028272
-Ref: figure-call-new-function1029364
-Node: Extension API Description1031426
-Node: Extension API Functions Introduction1033139
-Ref: table-api-std-headers1034975
-Node: General Data Types1039224
-Ref: General Data Types-Footnote-11047930
-Node: Memory Allocation Functions1048229
-Ref: Memory Allocation Functions-Footnote-11052730
-Node: Constructor Functions1052829
-Node: API Ownership of MPFR and GMP Values1056482
-Node: Registration Functions1057795
-Node: Extension Functions1058495
-Node: Exit Callback Functions1063817
-Node: Extension Version String1065067
-Node: Input Parsers1065730
-Node: Output Wrappers1078451
-Node: Two-way processors1082963
-Node: Printing Messages1085228
-Ref: Printing Messages-Footnote-11086399
-Node: Updating ERRNO1086552
-Node: Requesting Values1087291
-Ref: table-value-types-returned1088028
-Node: Accessing Parameters1089136
-Node: Symbol Table Access1090373
-Node: Symbol table by name1090885
-Ref: Symbol table by name-Footnote-11093910
-Node: Symbol table by cookie1094038
-Ref: Symbol table by cookie-Footnote-11098223
-Node: Cached values1098287
-Ref: Cached values-Footnote-11101823
-Node: Array Manipulation1101976
-Ref: Array Manipulation-Footnote-11103067
-Node: Array Data Types1103104
-Ref: Array Data Types-Footnote-11105762
-Node: Array Functions1105854
-Node: Flattening Arrays1110352
-Node: Creating Arrays1117328
-Node: Redirection API1122095
-Node: Extension API Variables1124928
-Node: Extension Versioning1125639
-Ref: gawk-api-version1126068
-Node: Extension GMP/MPFR Versioning1127799
-Node: Extension API Informational Variables1129427
-Node: Extension API Boilerplate1130500
-Node: Changes from API V11134474
-Node: Finding Extensions1136046
-Node: Extension Example1136605
-Node: Internal File Description1137403
-Node: Internal File Ops1141483
-Ref: Internal File Ops-Footnote-11152833
-Node: Using Internal File Ops1152973
-Ref: Using Internal File Ops-Footnote-11155356
-Node: Extension Samples1155630
-Node: Extension Sample File Functions1157159
-Node: Extension Sample Fnmatch1164808
-Node: Extension Sample Fork1166295
-Node: Extension Sample Inplace1167513
-Node: Extension Sample Ord1171139
-Node: Extension Sample Readdir1171975
-Ref: table-readdir-file-types1172864
-Node: Extension Sample Revout1173931
-Node: Extension Sample Rev2way1174520
-Node: Extension Sample Read write array1175260
-Node: Extension Sample Readfile1177202
-Node: Extension Sample Time1178297
-Node: Extension Sample API Tests1180049
-Node: gawkextlib1180541
-Node: Extension summary1183459
-Node: Extension Exercises1187161
-Node: Language History1188403
-Node: V7/SVR3.11190059
-Node: SVR41192211
-Node: POSIX1193645
-Node: BTL1195026
-Node: POSIX/GNU1195755
-Node: Feature History1201533
-Node: Common Extensions1218708
-Node: Ranges and Locales1219991
-Ref: Ranges and Locales-Footnote-11224607
-Ref: Ranges and Locales-Footnote-21224634
-Ref: Ranges and Locales-Footnote-31224869
-Node: Contributors1225092
-Node: History summary1231089
-Node: Installation1232469
-Node: Gawk Distribution1233413
-Node: Getting1233897
-Node: Extracting1234860
-Node: Distribution contents1236498
-Node: Unix Installation1243640
-Node: Quick Installation1244444
-Node: Compiling with MPFR1246920
-Node: Shell Startup Files1247612
-Node: Additional Configuration Options1248701
-Node: Configuration Philosophy1251016
-Node: Compiling from Git1253412
-Node: Building the Documentation1253967
-Node: Non-Unix Installation1255351
-Node: PC Installation1255811
-Node: PC Binary Installation1256649
-Node: PC Compiling1257084
-Node: PC Using1258201
-Node: Cygwin1261754
-Node: MSYS1262978
-Node: VMS Installation1263580
-Node: VMS Compilation1264299
-Ref: VMS Compilation-Footnote-11265528
-Node: VMS Dynamic Extensions1265586
-Node: VMS Installation Details1267271
-Node: VMS Running1269533
-Node: VMS GNV1273812
-Node: Bugs1274526
-Node: Bug definition1275438
-Node: Bug address1277942
-Node: Usenet1281330
-Node: Performance bugs1282339
-Node: Asking for help1285260
-Node: Maintainers1287222
-Node: Other Versions1288416
-Node: Installation summary1296268
-Node: Notes1297632
-Node: Compatibility Mode1298426
-Node: Additions1299208
-Node: Accessing The Source1300133
-Node: Adding Code1301570
-Node: New Ports1307789
-Node: Derived Files1312164
-Ref: Derived Files-Footnote-11317824
-Ref: Derived Files-Footnote-21317859
-Ref: Derived Files-Footnote-31318457
-Node: Future Extensions1318571
-Node: Implementation Limitations1319229
-Node: Extension Design1320439
-Node: Old Extension Problems1321583
-Ref: Old Extension Problems-Footnote-11323101
-Node: Extension New Mechanism Goals1323158
-Ref: Extension New Mechanism Goals-Footnote-11326522
-Node: Extension Other Design Decisions1326711
-Node: Extension Future Growth1328824
-Node: Notes summary1329430
-Node: Basic Concepts1330588
-Node: Basic High Level1331269
-Ref: figure-general-flow1331551
-Ref: figure-process-flow1332236
-Ref: Basic High Level-Footnote-11335537
-Node: Basic Data Typing1335722
-Node: Glossary1339050
-Node: Copying1370937
-Node: GNU Free Documentation License1408480
-Node: Index1433600
+Node: Switch Statement456661
+Node: Break Statement459102
+Node: Continue Statement461194
+Node: Next Statement463021
+Node: Nextfile Statement465404
+Node: Exit Statement468093
+Node: Built-in Variables470496
+Node: User-modified471629
+Node: Auto-set479396
+Ref: Auto-set-Footnote-1496203
+Ref: Auto-set-Footnote-2496409
+Node: ARGC and ARGV496465
+Node: Pattern Action Summary500678
+Node: Arrays503108
+Node: Array Basics504437
+Node: Array Intro505281
+Ref: figure-array-elements507256
+Ref: Array Intro-Footnote-1509960
+Node: Reference to Elements510088
+Node: Assigning Elements512552
+Node: Array Example513043
+Node: Scanning an Array514802
+Node: Controlling Scanning517824
+Ref: Controlling Scanning-Footnote-1524280
+Node: Numeric Array Subscripts524596
+Node: Uninitialized Subscripts526780
+Node: Delete528399
+Ref: Delete-Footnote-1531151
+Node: Multidimensional531208
+Node: Multiscanning534303
+Node: Arrays of Arrays535894
+Node: Arrays Summary540662
+Node: Functions542755
+Node: Built-in543793
+Node: Calling Built-in544946
+Node: Boolean Functions546942
+Node: Numeric Functions547496
+Ref: Numeric Functions-Footnote-1551523
+Ref: Numeric Functions-Footnote-2552171
+Ref: Numeric Functions-Footnote-3552219
+Node: String Functions552491
+Ref: String Functions-Footnote-1577006
+Ref: String Functions-Footnote-2577134
+Ref: String Functions-Footnote-3577382
+Node: Gory Details577469
+Ref: table-sub-escapes579260
+Ref: table-sub-proposed580779
+Ref: table-posix-sub582142
+Ref: table-gensub-escapes583683
+Ref: Gory Details-Footnote-1584506
+Node: I/O Functions584660
+Ref: table-system-return-values591114
+Ref: I/O Functions-Footnote-1593194
+Ref: I/O Functions-Footnote-2593342
+Node: Time Functions593462
+Ref: Time Functions-Footnote-1604133
+Ref: Time Functions-Footnote-2604201
+Ref: Time Functions-Footnote-3604359
+Ref: Time Functions-Footnote-4604470
+Ref: Time Functions-Footnote-5604582
+Ref: Time Functions-Footnote-6604809
+Node: Bitwise Functions605075
+Ref: table-bitwise-ops605669
+Ref: Bitwise Functions-Footnote-1611732
+Ref: Bitwise Functions-Footnote-2611905
+Node: Type Functions612096
+Node: I18N Functions615516
+Node: User-defined617167
+Node: Definition Syntax617979
+Ref: Definition Syntax-Footnote-1623673
+Node: Function Example623744
+Ref: Function Example-Footnote-1626666
+Node: Function Calling626688
+Node: Calling A Function627276
+Node: Variable Scope628234
+Node: Pass By Value/Reference631228
+Node: Function Caveats633872
+Ref: Function Caveats-Footnote-1635919
+Node: Return Statement636039
+Node: Dynamic Typing639018
+Node: Indirect Calls639948
+Ref: Indirect Calls-Footnote-1650203
+Node: Functions Summary650331
+Node: Library Functions653036
+Ref: Library Functions-Footnote-1656643
+Ref: Library Functions-Footnote-2656786
+Node: Library Names656957
+Ref: Library Names-Footnote-1660624
+Ref: Library Names-Footnote-2660847
+Node: General Functions660933
+Node: Strtonum Function662115
+Node: Assert Function665137
+Node: Round Function668463
+Node: Cliff Random Function670003
+Node: Ordinal Functions671019
+Ref: Ordinal Functions-Footnote-1674082
+Ref: Ordinal Functions-Footnote-2674334
+Node: Join Function674544
+Ref: Join Function-Footnote-1676314
+Node: Getlocaltime Function676514
+Node: Readfile Function680256
+Node: Shell Quoting682233
+Node: Isnumeric Function683661
+Node: Data File Management685049
+Node: Filetrans Function685681
+Node: Rewind Function689777
+Node: File Checking691686
+Ref: File Checking-Footnote-1693020
+Node: Empty Files693221
+Node: Ignoring Assigns695200
+Node: Getopt Function696750
+Ref: Getopt Function-Footnote-1711973
+Node: Passwd Functions712173
+Ref: Passwd Functions-Footnote-1721012
+Node: Group Functions721100
+Ref: Group Functions-Footnote-1728998
+Node: Walking Arrays729205
+Node: Library Functions Summary732213
+Node: Library Exercises733619
+Node: Sample Programs734084
+Node: Running Examples734854
+Node: Clones735582
+Node: Cut Program736806
+Node: Egrep Program746946
+Node: Id Program755947
+Node: Split Program765894
+Ref: Split Program-Footnote-1775787
+Node: Tee Program775960
+Node: Uniq Program778750
+Node: Wc Program786338
+Node: Bytes vs. Characters786725
+Node: Using extensions788273
+Node: wc program789027
+Node: Miscellaneous Programs793892
+Node: Dupword Program795105
+Node: Alarm Program797135
+Node: Translate Program801990
+Ref: Translate Program-Footnote-1806555
+Node: Labels Program806825
+Ref: Labels Program-Footnote-1810176
+Node: Word Sorting810260
+Node: History Sorting814332
+Node: Extract Program816557
+Node: Simple Sed824611
+Node: Igawk Program827685
+Ref: Igawk Program-Footnote-1842016
+Ref: Igawk Program-Footnote-2842218
+Ref: Igawk Program-Footnote-3842340
+Node: Anagram Program842455
+Node: Signature Program845517
+Node: Programs Summary846764
+Node: Programs Exercises847978
+Ref: Programs Exercises-Footnote-1852108
+Node: Advanced Features852194
+Node: Nondecimal Data854325
+Node: Boolean Typed Values855923
+Node: Array Sorting857804
+Node: Controlling Array Traversal858509
+Ref: Controlling Array Traversal-Footnote-1866877
+Node: Array Sorting Functions866995
+Ref: Array Sorting Functions-Footnote-1872369
+Node: Two-way I/O872565
+Ref: Two-way I/O-Footnote-1880291
+Ref: Two-way I/O-Footnote-2880478
+Node: TCP/IP Networking880560
+Node: Profiling883678
+Node: Extension Philosophy892987
+Node: Advanced Features Summary894466
+Node: Internationalization896481
+Node: I18N and L10N898155
+Node: Explaining gettext898842
+Ref: Explaining gettext-Footnote-1904734
+Ref: Explaining gettext-Footnote-2904919
+Node: Programmer i18n905084
+Ref: Programmer i18n-Footnote-1910033
+Node: Translator i18n910082
+Node: String Extraction910876
+Ref: String Extraction-Footnote-1912008
+Node: Printf Ordering912094
+Ref: Printf Ordering-Footnote-1914880
+Node: I18N Portability914944
+Ref: I18N Portability-Footnote-1917400
+Node: I18N Example917463
+Ref: I18N Example-Footnote-1920738
+Ref: I18N Example-Footnote-2920811
+Node: Gawk I18N920920
+Node: I18N Summary921569
+Node: Debugger922910
+Node: Debugging923910
+Node: Debugging Concepts924351
+Node: Debugging Terms926160
+Node: Awk Debugging928735
+Ref: Awk Debugging-Footnote-1929680
+Node: Sample Debugging Session929812
+Node: Debugger Invocation930346
+Node: Finding The Bug931732
+Node: List of Debugger Commands938206
+Node: Breakpoint Control939539
+Node: Debugger Execution Control943233
+Node: Viewing And Changing Data946595
+Node: Execution Stack950136
+Node: Debugger Info951773
+Node: Miscellaneous Debugger Commands955844
+Node: Readline Support960906
+Node: Limitations961802
+Node: Debugging Summary964356
+Node: Namespaces965635
+Node: Global Namespace966746
+Node: Qualified Names968144
+Node: Default Namespace969143
+Node: Changing The Namespace969884
+Node: Naming Rules971498
+Node: Internal Name Management973346
+Node: Namespace Example974388
+Node: Namespace And Features976950
+Node: Namespace Summary978385
+Node: Arbitrary Precision Arithmetic979862
+Node: Computer Arithmetic981349
+Ref: table-numeric-ranges985115
+Ref: table-floating-point-ranges985608
+Ref: Computer Arithmetic-Footnote-1986266
+Node: Math Definitions986323
+Ref: table-ieee-formats989299
+Node: MPFR features989866
+Node: FP Math Caution991584
+Ref: FP Math Caution-Footnote-1992656
+Node: Inexactness of computations993025
+Node: Inexact representation994056
+Node: Comparing FP Values995416
+Node: Errors accumulate996657
+Node: Strange values998113
+Ref: Strange values-Footnote-11000701
+Node: Getting Accuracy1000806
+Node: Try To Round1003516
+Node: Setting precision1004415
+Ref: table-predefined-precision-strings1005112
+Node: Setting the rounding mode1006942
+Ref: table-gawk-rounding-modes1007316
+Ref: Setting the rounding mode-Footnote-11011247
+Node: Arbitrary Precision Integers1011426
+Ref: Arbitrary Precision Integers-Footnote-11014601
+Node: Checking for MPFR1014750
+Node: POSIX Floating Point Problems1016224
+Ref: POSIX Floating Point Problems-Footnote-11020509
+Node: Floating point summary1020547
+Node: Dynamic Extensions1022737
+Node: Extension Intro1024290
+Node: Plugin License1025556
+Node: Extension Mechanism Outline1026353
+Ref: figure-load-extension1026792
+Ref: figure-register-new-function1028357
+Ref: figure-call-new-function1029449
+Node: Extension API Description1031511
+Node: Extension API Functions Introduction1033224
+Ref: table-api-std-headers1035060
+Node: General Data Types1039309
+Ref: General Data Types-Footnote-11048015
+Node: Memory Allocation Functions1048314
+Ref: Memory Allocation Functions-Footnote-11052815
+Node: Constructor Functions1052914
+Node: API Ownership of MPFR and GMP Values1056567
+Node: Registration Functions1057880
+Node: Extension Functions1058580
+Node: Exit Callback Functions1063902
+Node: Extension Version String1065152
+Node: Input Parsers1065815
+Node: Output Wrappers1078536
+Node: Two-way processors1083048
+Node: Printing Messages1085313
+Ref: Printing Messages-Footnote-11086484
+Node: Updating ERRNO1086637
+Node: Requesting Values1087376
+Ref: table-value-types-returned1088113
+Node: Accessing Parameters1089221
+Node: Symbol Table Access1090458
+Node: Symbol table by name1090970
+Ref: Symbol table by name-Footnote-11093995
+Node: Symbol table by cookie1094123
+Ref: Symbol table by cookie-Footnote-11098308
+Node: Cached values1098372
+Ref: Cached values-Footnote-11101908
+Node: Array Manipulation1102061
+Ref: Array Manipulation-Footnote-11103152
+Node: Array Data Types1103189
+Ref: Array Data Types-Footnote-11105847
+Node: Array Functions1105939
+Node: Flattening Arrays1110437
+Node: Creating Arrays1117413
+Node: Redirection API1122180
+Node: Extension API Variables1125013
+Node: Extension Versioning1125724
+Ref: gawk-api-version1126153
+Node: Extension GMP/MPFR Versioning1127884
+Node: Extension API Informational Variables1129512
+Node: Extension API Boilerplate1130585
+Node: Changes from API V11134559
+Node: Finding Extensions1136131
+Node: Extension Example1136690
+Node: Internal File Description1137488
+Node: Internal File Ops1141568
+Ref: Internal File Ops-Footnote-11152918
+Node: Using Internal File Ops1153058
+Ref: Using Internal File Ops-Footnote-11155441
+Node: Extension Samples1155715
+Node: Extension Sample File Functions1157244
+Node: Extension Sample Fnmatch1164893
+Node: Extension Sample Fork1166380
+Node: Extension Sample Inplace1167598
+Node: Extension Sample Ord1171224
+Node: Extension Sample Readdir1172060
+Ref: table-readdir-file-types1172949
+Node: Extension Sample Revout1174016
+Node: Extension Sample Rev2way1174605
+Node: Extension Sample Read write array1175345
+Node: Extension Sample Readfile1177287
+Node: Extension Sample Time1178382
+Node: Extension Sample API Tests1180134
+Node: gawkextlib1180626
+Node: Extension summary1183544
+Node: Extension Exercises1187246
+Node: Language History1188488
+Node: V7/SVR3.11190144
+Node: SVR41192296
+Node: POSIX1193730
+Node: BTL1195111
+Node: POSIX/GNU1195840
+Node: Feature History1201618
+Node: Common Extensions1218793
+Node: Ranges and Locales1220076
+Ref: Ranges and Locales-Footnote-11224692
+Ref: Ranges and Locales-Footnote-21224719
+Ref: Ranges and Locales-Footnote-31224954
+Node: Contributors1225177
+Node: History summary1231174
+Node: Installation1232554
+Node: Gawk Distribution1233498
+Node: Getting1233982
+Node: Extracting1234945
+Node: Distribution contents1236583
+Node: Unix Installation1243725
+Node: Quick Installation1244529
+Node: Compiling with MPFR1247005
+Node: Shell Startup Files1247697
+Node: Additional Configuration Options1248786
+Node: Configuration Philosophy1251101
+Node: Compiling from Git1253497
+Node: Building the Documentation1254052
+Node: Non-Unix Installation1255436
+Node: PC Installation1255896
+Node: PC Binary Installation1256734
+Node: PC Compiling1257169
+Node: PC Using1258286
+Node: Cygwin1261839
+Node: MSYS1263063
+Node: VMS Installation1263665
+Node: VMS Compilation1264384
+Ref: VMS Compilation-Footnote-11265613
+Node: VMS Dynamic Extensions1265671
+Node: VMS Installation Details1267356
+Node: VMS Running1269618
+Node: VMS GNV1273897
+Node: Bugs1274611
+Node: Bug definition1275523
+Node: Bug address1278459
+Node: Usenet1281847
+Node: Performance bugs1283036
+Node: Asking for help1285957
+Node: Maintainers1287924
+Node: Other Versions1289118
+Node: Installation summary1296970
+Node: Notes1298334
+Node: Compatibility Mode1299128
+Node: Additions1299910
+Node: Accessing The Source1300835
+Node: Adding Code1302272
+Node: New Ports1308491
+Node: Derived Files1312866
+Ref: Derived Files-Footnote-11318526
+Ref: Derived Files-Footnote-21318561
+Ref: Derived Files-Footnote-31319159
+Node: Future Extensions1319273
+Node: Implementation Limitations1319931
+Node: Extension Design1321141
+Node: Old Extension Problems1322285
+Ref: Old Extension Problems-Footnote-11323803
+Node: Extension New Mechanism Goals1323860
+Ref: Extension New Mechanism Goals-Footnote-11327224
+Node: Extension Other Design Decisions1327413
+Node: Extension Future Growth1329526
+Node: Notes summary1330132
+Node: Basic Concepts1331290
+Node: Basic High Level1331971
+Ref: figure-general-flow1332253
+Ref: figure-process-flow1332938
+Ref: Basic High Level-Footnote-11336239
+Node: Basic Data Typing1336424
+Node: Glossary1339752
+Node: Copying1371639
+Node: GNU Free Documentation License1409182
+Node: Index1434302
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 7bb56906..142708eb 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -15317,20 +15317,25 @@ awk '
 This prints the first three fields of each input record, with one
 input field per output line.
 
-It isn't possible to
-set more than one variable in the
-@var{initialization} part without using a multiple assignment statement
-such as @samp{x = y = 0}. This makes sense only if all the initial values
-are equal.  (But it is possible to initialize additional variables by writing
-their assignments as separate statements preceding the @code{for} loop.)
-
 @c @cindex comma operator, not supported
-The same is true of the @var{increment} part. Incrementing additional
-variables requires separate statements at the end of the loop.
-The C compound expression, using C's comma operator, is useful in
-this context, but it is not supported in @command{awk}.
+C and C++ programmers might expect to be able to use the comma
+operator to set more than one variable in the @var{initialization}
+part of the @code{for} loop, or to increment multiple variables in the
+@var{incrememnt} part of the loop, like so:
+
+@example
+for (i = 0, j = length(a); i < j; i++, j--) @dots{}   @ii{C/C++, not awk!}
+@end example
+
+@noindent
+You cannot do this; the comma operator is not supported in @command{awk}.
+There are workarounds, but they are nonobvious and can lead to
+code that is difficult to read and understand. It is best, therefore,
+to simply write additional initializations as separate statements
+preceding the @code{for} loop and to place additional increment statements
+at the end of the loop's body.
 
-Most often, @var{increment} is an increment expression, as in the previous
+Most often, @var{increment} is an increment expression, as in the earlier
 example.  But this is not required; it can be any expression
 whatsoever.  For example, the following statement prints all the powers of two
 between 1 and 100:
@@ -43280,7 +43285,7 @@ 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.''
+going to change.'' Here's the list:
 
 @itemize @bullet
 @item
@@ -43290,6 +43295,8 @@ 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.
+In short, just because @command{gawk} doesn't do what @emph{you}
+think it should, it's not necessarily a bug.
 
 @item
 Behaviors that are defined by the POSIX standard and/or for historical
@@ -43303,10 +43310,16 @@ 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.
 
+This applies also to differences in behavior between @command{gawk}
+and other language compilers and interpreters, such as wishes for more
+detailed descriptions of what the problem is when a syntax error is
+encountered.
+
 @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.
+you may have.  Its purpose is to teach you how to solve your problems
+on your own.
 
 @item
 General questions and discussion about @command{awk} programming or
@@ -43335,7 +43348,7 @@ 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.
+is out-of-date, the problem may already have been solved.
 
 @item
 Please see if setting the environment variable @env{LC_ALL}
@@ -43441,6 +43454,10 @@ Usenet/Internet newsgroup @code{comp.lang.awk}.  Although some of the
 @command{gawk} maintainer no longer does.  Thus it's virtually guaranteed
 that he will @emph{not} see your posting.
 
+If you really don't care about the previous paragraph and continue to
+post bug reports in @code{comp.lang.awk}, then understand that you're
+not reporting bugs, you're just whining.
+
 Similarly, posting bug reports or questions in web forums (such
 as @uref{https://stackoverflow.com/, Stack Overflow}) may get you
 an answer, but it won't be from the @command{gawk} maintainers,
@@ -43565,7 +43582,7 @@ After two such requests you will be silently @emph{blacklisted} from the bug lis
 
 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
+GNU Kind Communication Guidelines} in your correspondence on the help
 list (as well as off of it).
 
 @cindex Proulx, Bob
@@ -43573,7 +43590,6 @@ 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
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index ddb0f5ae..c79dd87f 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -14504,20 +14504,25 @@ awk '
 This prints the first three fields of each input record, with one
 input field per output line.
 
-It isn't possible to
-set more than one variable in the
-@var{initialization} part without using a multiple assignment statement
-such as @samp{x = y = 0}. This makes sense only if all the initial values
-are equal.  (But it is possible to initialize additional variables by writing
-their assignments as separate statements preceding the @code{for} loop.)
-
 @c @cindex comma operator, not supported
-The same is true of the @var{increment} part. Incrementing additional
-variables requires separate statements at the end of the loop.
-The C compound expression, using C's comma operator, is useful in
-this context, but it is not supported in @command{awk}.
+C and C++ programmers might expect to be able to use the comma
+operator to set more than one variable in the @var{initialization}
+part of the @code{for} loop, or to increment multiple variables in the
+@var{incrememnt} part of the loop, like so:
+
+@example
+for (i = 0, j = length(a); i < j; i++, j--) @dots{}   @ii{C/C++, not awk!}
+@end example
+
+@noindent
+You cannot do this; the comma operator is not supported in @command{awk}.
+There are workarounds, but they are nonobvious and can lead to
+code that is difficult to read and understand. It is best, therefore,
+to simply write additional initializations as separate statements
+preceding the @code{for} loop and to place additional increment statements
+at the end of the loop's body.
 
-Most often, @var{increment} is an increment expression, as in the previous
+Most often, @var{increment} is an increment expression, as in the earlier
 example.  But this is not required; it can be any expression
 whatsoever.  For example, the following statement prints all the powers of two
 between 1 and 100:
@@ -42123,7 +42128,7 @@ 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.''
+going to change.'' Here's the list:
 
 @itemize @bullet
 @item
@@ -42133,6 +42138,8 @@ 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.
+In short, just because @command{gawk} doesn't do what @emph{you}
+think it should, it's not necessarily a bug.
 
 @item
 Behaviors that are defined by the POSIX standard and/or for historical
@@ -42146,10 +42153,16 @@ 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.
 
+This applies also to differences in behavior between @command{gawk}
+and other language compilers and interpreters, such as wishes for more
+detailed descriptions of what the problem is when a syntax error is
+encountered.
+
 @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.
+you may have.  Its purpose is to teach you how to solve your problems
+on your own.
 
 @item
 General questions and discussion about @command{awk} programming or
@@ -42178,7 +42191,7 @@ 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.
+is out-of-date, the problem may already have been solved.
 
 @item
 Please see if setting the environment variable @env{LC_ALL}
@@ -42284,6 +42297,10 @@ Usenet/Internet newsgroup @code{comp.lang.awk}.  Although some of the
 @command{gawk} maintainer no longer does.  Thus it's virtually guaranteed
 that he will @emph{not} see your posting.
 
+If you really don't care about the previous paragraph and continue to
+post bug reports in @code{comp.lang.awk}, then understand that you're
+not reporting bugs, you're just whining.
+
 Similarly, posting bug reports or questions in web forums (such
 as @uref{https://stackoverflow.com/, Stack Overflow}) may get you
 an answer, but it won't be from the @command{gawk} maintainers,
@@ -42408,7 +42425,7 @@ After two such requests you will be silently @emph{blacklisted} from the bug lis
 
 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
+GNU Kind Communication Guidelines} in your correspondence on the help
 list (as well as off of it).
 
 @cindex Proulx, Bob
@@ -42416,7 +42433,6 @@ 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