And more doc updates.

4 files changed, 505 insertions, 449 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 7a1f8c61..e527b5c1 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-01         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Clarify typeof() usage with array elements
diff --git a/doc/gawk.info b/doc/gawk.info
index 1c7dfa20..f748cda9 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -10578,18 +10578,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:
@@ -31574,13 +31577,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
@@ -31592,9 +31598,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
@@ -31620,7 +31632,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
@@ -31701,6 +31713,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
@@ -31796,7 +31812,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
@@ -37013,7 +37029,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)
@@ -37233,7 +37249,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)
@@ -38716,403 +38732,403 @@ Node: If Statement448334
 Node: While Statement449829
 Node: Do Statement451857
 Node: For Statement453005
-Node: Switch Statement456176
-Node: Break Statement458617
-Node: Continue Statement460709
-Node: Next Statement462536
-Node: Nextfile Statement464919
-Node: Exit Statement467608
-Node: Built-in Variables470011
-Node: User-modified471144
-Node: Auto-set478911
-Ref: Auto-set-Footnote-1495718
-Ref: Auto-set-Footnote-2495924
-Node: ARGC and ARGV495980
-Node: Pattern Action Summary500193
-Node: Arrays502623
-Node: Array Basics503952
-Node: Array Intro504796
-Ref: figure-array-elements506771
-Ref: Array Intro-Footnote-1509475
-Node: Reference to Elements509603
-Node: Assigning Elements512067
-Node: Array Example512558
-Node: Scanning an Array514317
-Node: Controlling Scanning517339
-Ref: Controlling Scanning-Footnote-1523795
-Node: Numeric Array Subscripts524111
-Node: Uninitialized Subscripts526295
-Node: Delete527914
-Ref: Delete-Footnote-1530666
-Node: Multidimensional530723
-Node: Multiscanning533818
-Node: Arrays of Arrays535409
-Node: Arrays Summary540177
-Node: Functions542270
-Node: Built-in543308
-Node: Calling Built-in544389
-Node: Numeric Functions546385
-Ref: Numeric Functions-Footnote-1550413
-Ref: Numeric Functions-Footnote-2551061
-Ref: Numeric Functions-Footnote-3551109
-Node: String Functions551381
-Ref: String Functions-Footnote-1575896
-Ref: String Functions-Footnote-2576024
-Ref: String Functions-Footnote-3576272
-Node: Gory Details576359
-Ref: table-sub-escapes578150
-Ref: table-sub-proposed579669
-Ref: table-posix-sub581032
-Ref: table-gensub-escapes582573
-Ref: Gory Details-Footnote-1583396
-Node: I/O Functions583550
-Ref: table-system-return-values590004
-Ref: I/O Functions-Footnote-1592084
-Ref: I/O Functions-Footnote-2592232
-Node: Time Functions592352
-Ref: Time Functions-Footnote-1603023
-Ref: Time Functions-Footnote-2603091
-Ref: Time Functions-Footnote-3603249
-Ref: Time Functions-Footnote-4603360
-Ref: Time Functions-Footnote-5603472
-Ref: Time Functions-Footnote-6603699
-Node: Bitwise Functions603965
-Ref: table-bitwise-ops604559
-Ref: Bitwise Functions-Footnote-1610622
-Ref: Bitwise Functions-Footnote-2610795
-Node: Type Functions610986
-Node: I18N Functions614505
-Node: User-defined616156
-Node: Definition Syntax616968
-Ref: Definition Syntax-Footnote-1622662
-Node: Function Example622733
-Ref: Function Example-Footnote-1625655
-Node: Function Calling625677
-Node: Calling A Function626265
-Node: Variable Scope627223
-Node: Pass By Value/Reference630217
-Node: Function Caveats632861
-Ref: Function Caveats-Footnote-1634908
-Node: Return Statement635028
-Node: Dynamic Typing638007
-Node: Indirect Calls638937
-Ref: Indirect Calls-Footnote-1649189
-Node: Functions Summary649317
-Node: Library Functions652022
-Ref: Library Functions-Footnote-1655629
-Ref: Library Functions-Footnote-2655772
-Node: Library Names655943
-Ref: Library Names-Footnote-1659610
-Ref: Library Names-Footnote-2659833
-Node: General Functions659919
-Node: Strtonum Function661101
-Node: Assert Function664123
-Node: Round Function667449
-Node: Cliff Random Function668989
-Node: Ordinal Functions670005
-Ref: Ordinal Functions-Footnote-1673068
-Ref: Ordinal Functions-Footnote-2673320
-Node: Join Function673530
-Ref: Join Function-Footnote-1675300
-Node: Getlocaltime Function675500
-Node: Readfile Function679242
-Node: Shell Quoting681219
-Node: Isnumeric Function682647
-Node: Data File Management684035
-Node: Filetrans Function684667
-Node: Rewind Function688763
-Node: File Checking690672
-Ref: File Checking-Footnote-1692006
-Node: Empty Files692207
-Node: Ignoring Assigns694186
-Node: Getopt Function695736
-Ref: Getopt Function-Footnote-1710959
-Node: Passwd Functions711159
-Ref: Passwd Functions-Footnote-1719998
-Node: Group Functions720086
-Ref: Group Functions-Footnote-1727984
-Node: Walking Arrays728191
-Node: Library Functions Summary731199
-Node: Library Exercises732605
-Node: Sample Programs733070
-Node: Running Examples733840
-Node: Clones734568
-Node: Cut Program735792
-Node: Egrep Program745932
-Node: Id Program754933
-Node: Split Program764880
-Ref: Split Program-Footnote-1774773
-Node: Tee Program774946
-Node: Uniq Program777736
-Node: Wc Program785324
-Node: Bytes vs. Characters785711
-Node: Using extensions787259
-Node: wc program788013
-Node: Miscellaneous Programs792878
-Node: Dupword Program794091
-Node: Alarm Program796121
-Node: Translate Program800976
-Ref: Translate Program-Footnote-1805541
-Node: Labels Program805811
-Ref: Labels Program-Footnote-1809162
-Node: Word Sorting809246
-Node: History Sorting813318
-Node: Extract Program815543
-Node: Simple Sed823597
-Node: Igawk Program826671
-Ref: Igawk Program-Footnote-1841002
-Ref: Igawk Program-Footnote-2841204
-Ref: Igawk Program-Footnote-3841326
-Node: Anagram Program841441
-Node: Signature Program844503
-Node: Programs Summary845750
-Node: Programs Exercises846964
-Ref: Programs Exercises-Footnote-1851094
-Node: Advanced Features851180
-Node: Nondecimal Data853247
-Node: Array Sorting854838
-Node: Controlling Array Traversal855538
-Ref: Controlling Array Traversal-Footnote-1863906
-Node: Array Sorting Functions864024
-Ref: Array Sorting Functions-Footnote-1869398
-Node: Two-way I/O869594
-Ref: Two-way I/O-Footnote-1877320
-Ref: Two-way I/O-Footnote-2877507
-Node: TCP/IP Networking877589
-Node: Profiling880707
-Node: Extension Philosophy890016
-Node: Advanced Features Summary891495
-Node: Internationalization893510
-Node: I18N and L10N895184
-Node: Explaining gettext895871
-Ref: Explaining gettext-Footnote-1901763
-Ref: Explaining gettext-Footnote-2901948
-Node: Programmer i18n902113
-Ref: Programmer i18n-Footnote-1907062
-Node: Translator i18n907111
-Node: String Extraction907905
-Ref: String Extraction-Footnote-1909037
-Node: Printf Ordering909123
-Ref: Printf Ordering-Footnote-1911909
-Node: I18N Portability911973
-Ref: I18N Portability-Footnote-1914429
-Node: I18N Example914492
-Ref: I18N Example-Footnote-1917767
-Ref: I18N Example-Footnote-2917840
-Node: Gawk I18N917949
-Node: I18N Summary918598
-Node: Debugger919939
-Node: Debugging920939
-Node: Debugging Concepts921380
-Node: Debugging Terms923189
-Node: Awk Debugging925764
-Ref: Awk Debugging-Footnote-1926709
-Node: Sample Debugging Session926841
-Node: Debugger Invocation927375
-Node: Finding The Bug928761
-Node: List of Debugger Commands935235
-Node: Breakpoint Control936568
-Node: Debugger Execution Control940262
-Node: Viewing And Changing Data943624
-Node: Execution Stack947165
-Node: Debugger Info948802
-Node: Miscellaneous Debugger Commands952873
-Node: Readline Support957935
-Node: Limitations958831
-Node: Debugging Summary961385
-Node: Namespaces962664
-Node: Global Namespace963775
-Node: Qualified Names965173
-Node: Default Namespace966172
-Node: Changing The Namespace966913
-Node: Naming Rules968527
-Node: Internal Name Management970375
-Node: Namespace Example971417
-Node: Namespace And Features973979
-Node: Namespace Summary975414
-Node: Arbitrary Precision Arithmetic976891
-Node: Computer Arithmetic978378
-Ref: table-numeric-ranges982144
-Ref: table-floating-point-ranges982637
-Ref: Computer Arithmetic-Footnote-1983295
-Node: Math Definitions983352
-Ref: table-ieee-formats986668
-Ref: Math Definitions-Footnote-1987271
-Node: MPFR features987376
-Node: FP Math Caution989094
-Ref: FP Math Caution-Footnote-1990166
-Node: Inexactness of computations990535
-Node: Inexact representation991495
-Node: Comparing FP Values992855
-Node: Errors accumulate994096
-Node: Getting Accuracy995529
-Node: Try To Round998239
-Node: Setting precision999138
-Ref: table-predefined-precision-strings999835
-Node: Setting the rounding mode1001665
-Ref: table-gawk-rounding-modes1002039
-Ref: Setting the rounding mode-Footnote-11005970
-Node: Arbitrary Precision Integers1006149
-Ref: Arbitrary Precision Integers-Footnote-11009324
-Node: Checking for MPFR1009473
-Node: POSIX Floating Point Problems1010947
-Ref: POSIX Floating Point Problems-Footnote-11015232
-Node: Floating point summary1015270
-Node: Dynamic Extensions1017460
-Node: Extension Intro1019013
-Node: Plugin License1020279
-Node: Extension Mechanism Outline1021076
-Ref: figure-load-extension1021515
-Ref: figure-register-new-function1023080
-Ref: figure-call-new-function1024172
-Node: Extension API Description1026234
-Node: Extension API Functions Introduction1027947
-Ref: table-api-std-headers1029783
-Node: General Data Types1034032
-Ref: General Data Types-Footnote-11042662
-Node: Memory Allocation Functions1042961
-Ref: Memory Allocation Functions-Footnote-11047462
-Node: Constructor Functions1047561
-Node: API Ownership of MPFR and GMP Values1051027
-Node: Registration Functions1052340
-Node: Extension Functions1053040
-Node: Exit Callback Functions1058362
-Node: Extension Version String1059612
-Node: Input Parsers1060275
-Node: Output Wrappers1072996
-Node: Two-way processors1077508
-Node: Printing Messages1079773
-Ref: Printing Messages-Footnote-11080944
-Node: Updating ERRNO1081097
-Node: Requesting Values1081836
-Ref: table-value-types-returned1082573
-Node: Accessing Parameters1083509
-Node: Symbol Table Access1084746
-Node: Symbol table by name1085258
-Ref: Symbol table by name-Footnote-11088283
-Node: Symbol table by cookie1088411
-Ref: Symbol table by cookie-Footnote-11092596
-Node: Cached values1092660
-Ref: Cached values-Footnote-11096196
-Node: Array Manipulation1096349
-Ref: Array Manipulation-Footnote-11097440
-Node: Array Data Types1097477
-Ref: Array Data Types-Footnote-11100135
-Node: Array Functions1100227
-Node: Flattening Arrays1104725
-Node: Creating Arrays1111701
-Node: Redirection API1116468
-Node: Extension API Variables1119301
-Node: Extension Versioning1120012
-Ref: gawk-api-version1120441
-Node: Extension GMP/MPFR Versioning1122172
-Node: Extension API Informational Variables1123800
-Node: Extension API Boilerplate1124873
-Node: Changes from API V11128847
-Node: Finding Extensions1130419
-Node: Extension Example1130978
-Node: Internal File Description1131776
-Node: Internal File Ops1135856
-Ref: Internal File Ops-Footnote-11147206
-Node: Using Internal File Ops1147346
-Ref: Using Internal File Ops-Footnote-11149729
-Node: Extension Samples1150003
-Node: Extension Sample File Functions1151532
-Node: Extension Sample Fnmatch1159181
-Node: Extension Sample Fork1160668
-Node: Extension Sample Inplace1161886
-Node: Extension Sample Ord1165512
-Node: Extension Sample Readdir1166348
-Ref: table-readdir-file-types1167237
-Node: Extension Sample Revout1168304
-Node: Extension Sample Rev2way1168893
-Node: Extension Sample Read write array1169633
-Node: Extension Sample Readfile1171575
-Node: Extension Sample Time1172670
-Node: Extension Sample API Tests1174422
-Node: gawkextlib1174914
-Node: Extension summary1177832
-Node: Extension Exercises1181534
-Node: Language History1182776
-Node: V7/SVR3.11184432
-Node: SVR41186584
-Node: POSIX1188018
-Node: BTL1189399
-Node: POSIX/GNU1190128
-Node: Feature History1195906
-Node: Common Extensions1213081
-Node: Ranges and Locales1214364
-Ref: Ranges and Locales-Footnote-11218980
-Ref: Ranges and Locales-Footnote-21219007
-Ref: Ranges and Locales-Footnote-31219242
-Node: Contributors1219465
-Node: History summary1225462
-Node: Installation1226842
-Node: Gawk Distribution1227786
-Node: Getting1228270
-Node: Extracting1229233
-Node: Distribution contents1230871
-Node: Unix Installation1238013
-Node: Quick Installation1238817
-Node: Compiling with MPFR1241293
-Node: Shell Startup Files1241985
-Node: Additional Configuration Options1243074
-Node: Configuration Philosophy1245389
-Node: Compiling from Git1247785
-Node: Building the Documentation1248340
-Node: Non-Unix Installation1249724
-Node: PC Installation1250184
-Node: PC Binary Installation1251022
-Node: PC Compiling1251457
-Node: PC Using1252574
-Node: Cygwin1256127
-Node: MSYS1257351
-Node: VMS Installation1257953
-Node: VMS Compilation1258672
-Ref: VMS Compilation-Footnote-11259901
-Node: VMS Dynamic Extensions1259959
-Node: VMS Installation Details1261644
-Node: VMS Running1263906
-Node: VMS GNV1268185
-Node: Bugs1268899
-Node: Bug definition1269811
-Node: Bug address1272315
-Node: Usenet1275703
-Node: Performance bugs1276712
-Node: Asking for help1279633
-Node: Maintainers1281595
-Node: Other Versions1282789
-Node: Installation summary1290641
-Node: Notes1292005
-Node: Compatibility Mode1292799
-Node: Additions1293581
-Node: Accessing The Source1294506
-Node: Adding Code1295943
-Node: New Ports1302162
-Node: Derived Files1306537
-Ref: Derived Files-Footnote-11312197
-Ref: Derived Files-Footnote-21312232
-Ref: Derived Files-Footnote-31312830
-Node: Future Extensions1312944
-Node: Implementation Limitations1313602
-Node: Extension Design1314812
-Node: Old Extension Problems1315956
-Ref: Old Extension Problems-Footnote-11317474
-Node: Extension New Mechanism Goals1317531
-Ref: Extension New Mechanism Goals-Footnote-11320895
-Node: Extension Other Design Decisions1321084
-Node: Extension Future Growth1323197
-Node: Notes summary1323803
-Node: Basic Concepts1324961
-Node: Basic High Level1325642
-Ref: figure-general-flow1325924
-Ref: figure-process-flow1326609
-Ref: Basic High Level-Footnote-11329910
-Node: Basic Data Typing1330095
-Node: Glossary1333423
-Node: Copying1365308
-Node: GNU Free Documentation License1402851
-Node: Index1427971
+Node: Switch Statement456261
+Node: Break Statement458702
+Node: Continue Statement460794
+Node: Next Statement462621
+Node: Nextfile Statement465004
+Node: Exit Statement467693
+Node: Built-in Variables470096
+Node: User-modified471229
+Node: Auto-set478996
+Ref: Auto-set-Footnote-1495803
+Ref: Auto-set-Footnote-2496009
+Node: ARGC and ARGV496065
+Node: Pattern Action Summary500278
+Node: Arrays502708
+Node: Array Basics504037
+Node: Array Intro504881
+Ref: figure-array-elements506856
+Ref: Array Intro-Footnote-1509560
+Node: Reference to Elements509688
+Node: Assigning Elements512152
+Node: Array Example512643
+Node: Scanning an Array514402
+Node: Controlling Scanning517424
+Ref: Controlling Scanning-Footnote-1523880
+Node: Numeric Array Subscripts524196
+Node: Uninitialized Subscripts526380
+Node: Delete527999
+Ref: Delete-Footnote-1530751
+Node: Multidimensional530808
+Node: Multiscanning533903
+Node: Arrays of Arrays535494
+Node: Arrays Summary540262
+Node: Functions542355
+Node: Built-in543393
+Node: Calling Built-in544474
+Node: Numeric Functions546470
+Ref: Numeric Functions-Footnote-1550498
+Ref: Numeric Functions-Footnote-2551146
+Ref: Numeric Functions-Footnote-3551194
+Node: String Functions551466
+Ref: String Functions-Footnote-1575981
+Ref: String Functions-Footnote-2576109
+Ref: String Functions-Footnote-3576357
+Node: Gory Details576444
+Ref: table-sub-escapes578235
+Ref: table-sub-proposed579754
+Ref: table-posix-sub581117
+Ref: table-gensub-escapes582658
+Ref: Gory Details-Footnote-1583481
+Node: I/O Functions583635
+Ref: table-system-return-values590089
+Ref: I/O Functions-Footnote-1592169
+Ref: I/O Functions-Footnote-2592317
+Node: Time Functions592437
+Ref: Time Functions-Footnote-1603108
+Ref: Time Functions-Footnote-2603176
+Ref: Time Functions-Footnote-3603334
+Ref: Time Functions-Footnote-4603445
+Ref: Time Functions-Footnote-5603557
+Ref: Time Functions-Footnote-6603784
+Node: Bitwise Functions604050
+Ref: table-bitwise-ops604644
+Ref: Bitwise Functions-Footnote-1610707
+Ref: Bitwise Functions-Footnote-2610880
+Node: Type Functions611071
+Node: I18N Functions614590
+Node: User-defined616241
+Node: Definition Syntax617053
+Ref: Definition Syntax-Footnote-1622747
+Node: Function Example622818
+Ref: Function Example-Footnote-1625740
+Node: Function Calling625762
+Node: Calling A Function626350
+Node: Variable Scope627308
+Node: Pass By Value/Reference630302
+Node: Function Caveats632946
+Ref: Function Caveats-Footnote-1634993
+Node: Return Statement635113
+Node: Dynamic Typing638092
+Node: Indirect Calls639022
+Ref: Indirect Calls-Footnote-1649274
+Node: Functions Summary649402
+Node: Library Functions652107
+Ref: Library Functions-Footnote-1655714
+Ref: Library Functions-Footnote-2655857
+Node: Library Names656028
+Ref: Library Names-Footnote-1659695
+Ref: Library Names-Footnote-2659918
+Node: General Functions660004
+Node: Strtonum Function661186
+Node: Assert Function664208
+Node: Round Function667534
+Node: Cliff Random Function669074
+Node: Ordinal Functions670090
+Ref: Ordinal Functions-Footnote-1673153
+Ref: Ordinal Functions-Footnote-2673405
+Node: Join Function673615
+Ref: Join Function-Footnote-1675385
+Node: Getlocaltime Function675585
+Node: Readfile Function679327
+Node: Shell Quoting681304
+Node: Isnumeric Function682732
+Node: Data File Management684120
+Node: Filetrans Function684752
+Node: Rewind Function688848
+Node: File Checking690757
+Ref: File Checking-Footnote-1692091
+Node: Empty Files692292
+Node: Ignoring Assigns694271
+Node: Getopt Function695821
+Ref: Getopt Function-Footnote-1711044
+Node: Passwd Functions711244
+Ref: Passwd Functions-Footnote-1720083
+Node: Group Functions720171
+Ref: Group Functions-Footnote-1728069
+Node: Walking Arrays728276
+Node: Library Functions Summary731284
+Node: Library Exercises732690
+Node: Sample Programs733155
+Node: Running Examples733925
+Node: Clones734653
+Node: Cut Program735877
+Node: Egrep Program746017
+Node: Id Program755018
+Node: Split Program764965
+Ref: Split Program-Footnote-1774858
+Node: Tee Program775031
+Node: Uniq Program777821
+Node: Wc Program785409
+Node: Bytes vs. Characters785796
+Node: Using extensions787344
+Node: wc program788098
+Node: Miscellaneous Programs792963
+Node: Dupword Program794176
+Node: Alarm Program796206
+Node: Translate Program801061
+Ref: Translate Program-Footnote-1805626
+Node: Labels Program805896
+Ref: Labels Program-Footnote-1809247
+Node: Word Sorting809331
+Node: History Sorting813403
+Node: Extract Program815628
+Node: Simple Sed823682
+Node: Igawk Program826756
+Ref: Igawk Program-Footnote-1841087
+Ref: Igawk Program-Footnote-2841289
+Ref: Igawk Program-Footnote-3841411
+Node: Anagram Program841526
+Node: Signature Program844588
+Node: Programs Summary845835
+Node: Programs Exercises847049
+Ref: Programs Exercises-Footnote-1851179
+Node: Advanced Features851265
+Node: Nondecimal Data853332
+Node: Array Sorting854923
+Node: Controlling Array Traversal855623
+Ref: Controlling Array Traversal-Footnote-1863991
+Node: Array Sorting Functions864109
+Ref: Array Sorting Functions-Footnote-1869483
+Node: Two-way I/O869679
+Ref: Two-way I/O-Footnote-1877405
+Ref: Two-way I/O-Footnote-2877592
+Node: TCP/IP Networking877674
+Node: Profiling880792
+Node: Extension Philosophy890101
+Node: Advanced Features Summary891580
+Node: Internationalization893595
+Node: I18N and L10N895269
+Node: Explaining gettext895956
+Ref: Explaining gettext-Footnote-1901848
+Ref: Explaining gettext-Footnote-2902033
+Node: Programmer i18n902198
+Ref: Programmer i18n-Footnote-1907147
+Node: Translator i18n907196
+Node: String Extraction907990
+Ref: String Extraction-Footnote-1909122
+Node: Printf Ordering909208
+Ref: Printf Ordering-Footnote-1911994
+Node: I18N Portability912058
+Ref: I18N Portability-Footnote-1914514
+Node: I18N Example914577
+Ref: I18N Example-Footnote-1917852
+Ref: I18N Example-Footnote-2917925
+Node: Gawk I18N918034
+Node: I18N Summary918683
+Node: Debugger920024
+Node: Debugging921024
+Node: Debugging Concepts921465
+Node: Debugging Terms923274
+Node: Awk Debugging925849
+Ref: Awk Debugging-Footnote-1926794
+Node: Sample Debugging Session926926
+Node: Debugger Invocation927460
+Node: Finding The Bug928846
+Node: List of Debugger Commands935320
+Node: Breakpoint Control936653
+Node: Debugger Execution Control940347
+Node: Viewing And Changing Data943709
+Node: Execution Stack947250
+Node: Debugger Info948887
+Node: Miscellaneous Debugger Commands952958
+Node: Readline Support958020
+Node: Limitations958916
+Node: Debugging Summary961470
+Node: Namespaces962749
+Node: Global Namespace963860
+Node: Qualified Names965258
+Node: Default Namespace966257
+Node: Changing The Namespace966998
+Node: Naming Rules968612
+Node: Internal Name Management970460
+Node: Namespace Example971502
+Node: Namespace And Features974064
+Node: Namespace Summary975499
+Node: Arbitrary Precision Arithmetic976976
+Node: Computer Arithmetic978463
+Ref: table-numeric-ranges982229
+Ref: table-floating-point-ranges982722
+Ref: Computer Arithmetic-Footnote-1983380
+Node: Math Definitions983437
+Ref: table-ieee-formats986753
+Ref: Math Definitions-Footnote-1987356
+Node: MPFR features987461
+Node: FP Math Caution989179
+Ref: FP Math Caution-Footnote-1990251
+Node: Inexactness of computations990620
+Node: Inexact representation991580
+Node: Comparing FP Values992940
+Node: Errors accumulate994181
+Node: Getting Accuracy995614
+Node: Try To Round998324
+Node: Setting precision999223
+Ref: table-predefined-precision-strings999920
+Node: Setting the rounding mode1001750
+Ref: table-gawk-rounding-modes1002124
+Ref: Setting the rounding mode-Footnote-11006055
+Node: Arbitrary Precision Integers1006234
+Ref: Arbitrary Precision Integers-Footnote-11009409
+Node: Checking for MPFR1009558
+Node: POSIX Floating Point Problems1011032
+Ref: POSIX Floating Point Problems-Footnote-11015317
+Node: Floating point summary1015355
+Node: Dynamic Extensions1017545
+Node: Extension Intro1019098
+Node: Plugin License1020364
+Node: Extension Mechanism Outline1021161
+Ref: figure-load-extension1021600
+Ref: figure-register-new-function1023165
+Ref: figure-call-new-function1024257
+Node: Extension API Description1026319
+Node: Extension API Functions Introduction1028032
+Ref: table-api-std-headers1029868
+Node: General Data Types1034117
+Ref: General Data Types-Footnote-11042747
+Node: Memory Allocation Functions1043046
+Ref: Memory Allocation Functions-Footnote-11047547
+Node: Constructor Functions1047646
+Node: API Ownership of MPFR and GMP Values1051112
+Node: Registration Functions1052425
+Node: Extension Functions1053125
+Node: Exit Callback Functions1058447
+Node: Extension Version String1059697
+Node: Input Parsers1060360
+Node: Output Wrappers1073081
+Node: Two-way processors1077593
+Node: Printing Messages1079858
+Ref: Printing Messages-Footnote-11081029
+Node: Updating ERRNO1081182
+Node: Requesting Values1081921
+Ref: table-value-types-returned1082658
+Node: Accessing Parameters1083594
+Node: Symbol Table Access1084831
+Node: Symbol table by name1085343
+Ref: Symbol table by name-Footnote-11088368
+Node: Symbol table by cookie1088496
+Ref: Symbol table by cookie-Footnote-11092681
+Node: Cached values1092745
+Ref: Cached values-Footnote-11096281
+Node: Array Manipulation1096434
+Ref: Array Manipulation-Footnote-11097525
+Node: Array Data Types1097562
+Ref: Array Data Types-Footnote-11100220
+Node: Array Functions1100312
+Node: Flattening Arrays1104810
+Node: Creating Arrays1111786
+Node: Redirection API1116553
+Node: Extension API Variables1119386
+Node: Extension Versioning1120097
+Ref: gawk-api-version1120526
+Node: Extension GMP/MPFR Versioning1122257
+Node: Extension API Informational Variables1123885
+Node: Extension API Boilerplate1124958
+Node: Changes from API V11128932
+Node: Finding Extensions1130504
+Node: Extension Example1131063
+Node: Internal File Description1131861
+Node: Internal File Ops1135941
+Ref: Internal File Ops-Footnote-11147291
+Node: Using Internal File Ops1147431
+Ref: Using Internal File Ops-Footnote-11149814
+Node: Extension Samples1150088
+Node: Extension Sample File Functions1151617
+Node: Extension Sample Fnmatch1159266
+Node: Extension Sample Fork1160753
+Node: Extension Sample Inplace1161971
+Node: Extension Sample Ord1165597
+Node: Extension Sample Readdir1166433
+Ref: table-readdir-file-types1167322
+Node: Extension Sample Revout1168389
+Node: Extension Sample Rev2way1168978
+Node: Extension Sample Read write array1169718
+Node: Extension Sample Readfile1171660
+Node: Extension Sample Time1172755
+Node: Extension Sample API Tests1174507
+Node: gawkextlib1174999
+Node: Extension summary1177917
+Node: Extension Exercises1181619
+Node: Language History1182861
+Node: V7/SVR3.11184517
+Node: SVR41186669
+Node: POSIX1188103
+Node: BTL1189484
+Node: POSIX/GNU1190213
+Node: Feature History1195991
+Node: Common Extensions1213166
+Node: Ranges and Locales1214449
+Ref: Ranges and Locales-Footnote-11219065
+Ref: Ranges and Locales-Footnote-21219092
+Ref: Ranges and Locales-Footnote-31219327
+Node: Contributors1219550
+Node: History summary1225547
+Node: Installation1226927
+Node: Gawk Distribution1227871
+Node: Getting1228355
+Node: Extracting1229318
+Node: Distribution contents1230956
+Node: Unix Installation1238098
+Node: Quick Installation1238902
+Node: Compiling with MPFR1241378
+Node: Shell Startup Files1242070
+Node: Additional Configuration Options1243159
+Node: Configuration Philosophy1245474
+Node: Compiling from Git1247870
+Node: Building the Documentation1248425
+Node: Non-Unix Installation1249809
+Node: PC Installation1250269
+Node: PC Binary Installation1251107
+Node: PC Compiling1251542
+Node: PC Using1252659
+Node: Cygwin1256212
+Node: MSYS1257436
+Node: VMS Installation1258038
+Node: VMS Compilation1258757
+Ref: VMS Compilation-Footnote-11259986
+Node: VMS Dynamic Extensions1260044
+Node: VMS Installation Details1261729
+Node: VMS Running1263991
+Node: VMS GNV1268270
+Node: Bugs1268984
+Node: Bug definition1269896
+Node: Bug address1272832
+Node: Usenet1276220
+Node: Performance bugs1277409
+Node: Asking for help1280330
+Node: Maintainers1282297
+Node: Other Versions1283491
+Node: Installation summary1291343
+Node: Notes1292707
+Node: Compatibility Mode1293501
+Node: Additions1294283
+Node: Accessing The Source1295208
+Node: Adding Code1296645
+Node: New Ports1302864
+Node: Derived Files1307239
+Ref: Derived Files-Footnote-11312899
+Ref: Derived Files-Footnote-21312934
+Ref: Derived Files-Footnote-31313532
+Node: Future Extensions1313646
+Node: Implementation Limitations1314304
+Node: Extension Design1315514
+Node: Old Extension Problems1316658
+Ref: Old Extension Problems-Footnote-11318176
+Node: Extension New Mechanism Goals1318233
+Ref: Extension New Mechanism Goals-Footnote-11321597
+Node: Extension Other Design Decisions1321786
+Node: Extension Future Growth1323899
+Node: Notes summary1324505
+Node: Basic Concepts1325663
+Node: Basic High Level1326344
+Ref: figure-general-flow1326626
+Ref: figure-process-flow1327311
+Ref: Basic High Level-Footnote-11330612
+Node: Basic Data Typing1330797
+Node: Glossary1334125
+Node: Copying1366010
+Node: GNU Free Documentation License1403553
+Node: Index1428673
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index c7099447..009272e8 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -15309,20 +15309,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:
@@ -42948,7 +42953,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
@@ -42958,6 +42963,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
@@ -42971,10 +42978,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
@@ -43003,7 +43016,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}
@@ -43109,6 +43122,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,
@@ -43233,7 +43250,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
@@ -43241,7 +43258,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 d874549e..38470352 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -14496,20 +14496,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:
@@ -41791,7 +41796,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
@@ -41801,6 +41806,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
@@ -41814,10 +41821,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
@@ -41846,7 +41859,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}
@@ -41952,6 +41965,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,
@@ -42076,7 +42093,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
@@ -42084,7 +42101,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