Merge branch 'gawk-5.1-stable'

4 files changed, 626 insertions, 550 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index b06cc6ad..6cf1fdb2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2021-01-08         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (gawk split records): Document that RS = "()"
+	doesn't split records on the null string.
+	(Regexp Field Splitting): Ditto, for FS.
+
 2020-12-28         Juergen Kahrs         <Juergen.Kahrs@googlemail.com>
 
 	* gawkinet.texi: Update mailpopclient.
diff --git a/doc/gawk.info b/doc/gawk.info
index ee2526ec..bf9a88d7 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -1,6 +1,6 @@
 This is gawk.info, produced by makeinfo version 6.7 from gawk.texi.
 
-Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2020
+Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2021
 Free Software Foundation, Inc.
 
 
@@ -37,7 +37,7 @@ General Introduction
 This file documents 'awk', a program that you can use to select
 particular records in a file and perform operations upon them.
 
-   Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2020
+   Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2021
 Free Software Foundation, Inc.
 
 
@@ -4633,13 +4633,21 @@ that could match the trailing part is fairly long.  'gawk' attempts to
 avoid this problem, but currently, there's no guarantee that this will
 never happen.
 
-     NOTE: Remember that in 'awk', the '^' and '$' anchor metacharacters
-     match the beginning and end of a _string_, and not the beginning
-     and end of a _line_.  As a result, something like 'RS =
-     "^[[:upper:]]"' can only match at the beginning of a file.  This is
-     because 'gawk' views the input file as one long string that happens
-     to contain newline characters.  It is thus best to avoid anchor
-     metacharacters in the value of 'RS'.
+            Caveats When Using Regular Expressions for 'RS'
+
+   Remember that in 'awk', the '^' and '$' anchor metacharacters match
+the beginning and end of a _string_, and not the beginning and end of a
+_line_.  As a result, something like 'RS = "^[[:upper:]]"' can only
+match at the beginning of a file.  This is because 'gawk' views the
+input file as one long string that happens to contain newline
+characters.  It is thus best to avoid anchor metacharacters in the value
+of 'RS'.
+
+   Record splitting with regular expressions works differently than
+regexp matching with the 'sub()', 'gsub()', and 'gensub()' (*note String
+Functions::).  Those functions allow a regexp to match the empty string;
+record splitting does not.  Thus, for example 'RS = "()"' does _not_
+split records between characters.
 
    The use of 'RS' as a regular expression and the 'RT' variable are
 'gawk' extensions; they are not available in compatibility mode (*note
@@ -5112,6 +5120,12 @@ beginning of the record.  'gawk' also works this way.  For example:
      -| -->xxBxx<--
      -| -->C<--
 
+   Finally, field splitting with regular expressions works differently
+than regexp matching with the 'sub()', 'gsub()', and 'gensub()' (*note
+String Functions::).  Those functions allow a regexp to match the empty
+string; field splitting does not.  Thus, for example 'FS = "()"' does
+_not_ split fields between characters.
+
 
 File: gawk.info,  Node: Single Character Fields,  Next: Command Line Field Separator,  Prev: Regexp Field Splitting,  Up: Field Separators
 
@@ -35282,7 +35296,7 @@ Index
 * Brian Kernighan's awk <1>:             Escape Sequences.    (line 112)
 * Brian Kernighan's awk <2>:             GNU Regexp Operators.
                                                               (line  85)
-* Brian Kernighan's awk <3>:             gawk split records.  (line  63)
+* Brian Kernighan's awk <3>:             gawk split records.  (line  71)
 * Brian Kernighan's awk <4>:             Regexp Field Splitting.
                                                               (line  67)
 * Brian Kernighan's awk <5>:             Getline/Pipe.        (line  62)
@@ -35549,7 +35563,7 @@ Index
 * dark corner, escape sequences, for metacharacters: Escape Sequences.
                                                               (line 144)
 * dark corner, input files:              awk split records.   (line 104)
-* dark corner, strings, storing:         gawk split records.  (line  86)
+* dark corner, strings, storing:         gawk split records.  (line  94)
 * dark corner, NF variable, decrementing: Changing Fields.    (line 107)
 * dark corner, ^, in FS:                 Regexp Field Splitting.
                                                               (line  59)
@@ -35777,9 +35791,9 @@ Index
 * differences in awk and gawk, RS/RT variables: awk split records.
                                                               (line 118)
 * differences in awk and gawk, RS/RT variables <1>: gawk split records.
-                                                              (line  58)
+                                                              (line  66)
 * differences in awk and gawk, strings, storing: gawk split records.
-                                                              (line  80)
+                                                              (line  88)
 * differences in awk and gawk, single-character fields: Single Character Fields.
                                                               (line   6)
 * differences in awk and gawk, RS/RT variables <2>: Multiple Line.
@@ -36326,7 +36340,7 @@ Index
                                                               (line  26)
 * gawk, IGNORECASE variable in:          Case-sensitivity.    (line  26)
 * gawk, RT variable in:                  awk split records.   (line 118)
-* gawk, RT variable in <1>:              gawk split records.  (line  58)
+* gawk, RT variable in <1>:              gawk split records.  (line  66)
 * gawk, FIELDWIDTHS variable in:         Fixed width data.    (line  17)
 * gawk, FPAT variable in:                Splitting By Content.
                                                               (line  29)
@@ -37089,7 +37103,7 @@ Index
 * portability, backslash in escape sequences: Escape Sequences.
                                                               (line 108)
 * portability, data files as single record: gawk split records.
-                                                              (line  69)
+                                                              (line  77)
 * portability, NF variable, decrementing: Changing Fields.    (line 115)
 * portability, close() function and:     Close Files And Pipes.
                                                               (line  81)
@@ -37334,7 +37348,7 @@ Index
 * records:                               Reading Files.       (line  14)
 * records, splitting input into:         Records.             (line   6)
 * records, terminating:                  awk split records.   (line 118)
-* records, treating files as:            gawk split records.  (line  96)
+* records, treating files as:            gawk split records.  (line 104)
 * records, multiline:                    Multiple Line.       (line   6)
 * records, printing:                     Print.               (line  22)
 * records <1>:                           Basic High Level.    (line  62)
@@ -37445,7 +37459,7 @@ Index
 * RSTART variable:                       Auto-set.            (line 341)
 * RSTART variable, match() function and: String Functions.    (line 234)
 * RT variable:                           awk split records.   (line 118)
-* RT variable <1>:                       gawk split records.  (line  58)
+* RT variable <1>:                       gawk split records.  (line  66)
 * RT variable <2>:                       Multiple Line.       (line 139)
 * RT variable <3>:                       Auto-set.            (line 348)
 * Rubin, Paul:                           History.             (line  30)
@@ -37569,7 +37583,9 @@ Index
                                                               (line 138)
 * sidebar, Using \n in Bracket Expressions of Dynamic Regexps: Computed Regexps.
                                                               (line  58)
-* sidebar, RS = "\0" Is Not Portable:    gawk split records.  (line  67)
+* sidebar, Caveats When Using Regular Expressions for RS: gawk split records.
+                                                              (line  50)
+* sidebar, RS = "\0" Is Not Portable:    gawk split records.  (line  75)
 * sidebar, Understanding $0:             Changing Fields.     (line 135)
 * sidebar, Changing FS Does Not Affect the Fields: Full Line Fields.
                                                               (line  14)
@@ -37614,7 +37630,7 @@ Index
 * single quote ('), vs. apostrophe:      Comments.            (line  27)
 * single quote ('), in shell commands:   Quoting.             (line  48)
 * single quote ('), with double quotes:  Quoting.             (line  73)
-* single records, treating files as:     gawk split records.  (line  96)
+* single records, treating files as:     gawk split records.  (line 104)
 * single-character fields:               Single Character Fields.
                                                               (line   6)
 * single-precision:                      Computer Arithmetic. (line  61)
@@ -37809,7 +37825,7 @@ Index
 * traceback, display in debugger:        Execution Stack.     (line  13)
 * translate string:                      I18N Functions.      (line  21)
 * translate.awk program:                 Translate Program.   (line  55)
-* treating files, as single records:     gawk split records.  (line  96)
+* treating files, as single records:     gawk split records.  (line 104)
 * troubleshooting, typographical errors, global variables: Options.
                                                               (line 103)
 * troubleshooting, --non-decimal-data option: Options.        (line 249)
@@ -38111,526 +38127,526 @@ Node: Reading Files200999
 Node: Records203268
 Node: awk split records204343
 Node: gawk split records209043
-Ref: gawk split records-Footnote-1213776
-Node: Fields213813
-Node: Nonconstant Fields216554
-Ref: Nonconstant Fields-Footnote-1218790
-Node: Changing Fields218994
-Node: Field Separators225025
-Node: Default Field Splitting227723
-Node: Regexp Field Splitting228841
-Node: Single Character Fields232194
-Node: Command Line Field Separator233254
-Node: Full Line Fields236472
-Ref: Full Line Fields-Footnote-1237994
-Ref: Full Line Fields-Footnote-2238040
-Node: Field Splitting Summary238141
-Node: Constant Size240215
-Node: Fixed width data240947
-Node: Skipping intervening244414
-Node: Allowing trailing data245212
-Node: Fields with fixed data246249
-Node: Splitting By Content247767
-Ref: Splitting By Content-Footnote-1251550
-Node: More CSV251713
-Node: Testing field creation253305
-Node: Multiple Line254930
-Node: Getline261207
-Node: Plain Getline263676
-Node: Getline/Variable266249
-Node: Getline/File267400
-Node: Getline/Variable/File268788
-Ref: Getline/Variable/File-Footnote-1270393
-Node: Getline/Pipe270481
-Node: Getline/Variable/Pipe273185
-Node: Getline/Coprocess274320
-Node: Getline/Variable/Coprocess275587
-Node: Getline Notes276329
-Node: Getline Summary279126
-Ref: table-getline-variants279550
-Node: Read Timeout280298
-Ref: Read Timeout-Footnote-1284204
-Node: Retrying Input284262
-Node: Command-line directories285461
-Node: Input Summary286367
-Node: Input Exercises289539
-Node: Printing289973
-Node: Print291807
-Node: Print Examples293264
-Node: Output Separators296044
-Node: OFMT298061
-Node: Printf299417
-Node: Basic Printf300202
-Node: Control Letters301776
-Node: Format Modifiers306938
-Node: Printf Examples312953
-Node: Redirection315439
-Node: Special FD322280
-Ref: Special FD-Footnote-1325448
-Node: Special Files325522
-Node: Other Inherited Files326139
-Node: Special Network327140
-Node: Special Caveats328000
-Node: Close Files And Pipes328949
-Ref: table-close-pipe-return-values335856
-Ref: Close Files And Pipes-Footnote-1336669
-Ref: Close Files And Pipes-Footnote-2336817
-Node: Nonfatal336969
-Node: Output Summary339307
-Node: Output Exercises340529
-Node: Expressions341208
-Node: Values342396
-Node: Constants343074
-Node: Scalar Constants343765
-Ref: Scalar Constants-Footnote-1346275
-Node: Nondecimal-numbers346525
-Node: Regexp Constants349526
-Node: Using Constant Regexps350052
-Node: Standard Regexp Constants350674
-Node: Strong Regexp Constants353862
-Node: Variables356874
-Node: Using Variables357531
-Node: Assignment Options359441
-Node: Conversion361912
-Node: Strings And Numbers362436
-Ref: Strings And Numbers-Footnote-1365499
-Node: Locale influences conversions365608
-Ref: table-locale-affects368366
-Node: All Operators368984
-Node: Arithmetic Ops369613
-Node: Concatenation372329
-Ref: Concatenation-Footnote-1375176
-Node: Assignment Ops375283
-Ref: table-assign-ops380274
-Node: Increment Ops381587
-Node: Truth Values and Conditions385047
-Node: Truth Values386121
-Node: Typing and Comparison387169
-Node: Variable Typing387989
-Ref: Variable Typing-Footnote-1394452
-Ref: Variable Typing-Footnote-2394524
-Node: Comparison Operators394601
-Ref: table-relational-ops395020
-Node: POSIX String Comparison398515
-Ref: POSIX String Comparison-Footnote-1400210
-Ref: POSIX String Comparison-Footnote-2400349
-Node: Boolean Ops400433
-Ref: Boolean Ops-Footnote-1404915
-Node: Conditional Exp405007
-Node: Function Calls406743
-Node: Precedence410620
-Node: Locales414279
-Node: Expressions Summary415911
-Node: Patterns and Actions418484
-Node: Pattern Overview419604
-Node: Regexp Patterns421281
-Node: Expression Patterns421823
-Node: Ranges425604
-Node: BEGIN/END428712
-Node: Using BEGIN/END429473
-Ref: Using BEGIN/END-Footnote-1432227
-Node: I/O And BEGIN/END432333
-Node: BEGINFILE/ENDFILE434646
-Node: Empty437877
-Node: Using Shell Variables438194
-Node: Action Overview440468
-Node: Statements442793
-Node: If Statement444641
-Node: While Statement446136
-Node: Do Statement448164
-Node: For Statement449312
-Node: Switch Statement452483
-Node: Break Statement454924
-Node: Continue Statement457016
-Node: Next Statement458843
-Node: Nextfile Statement461226
-Node: Exit Statement463915
-Node: Built-in Variables466318
-Node: User-modified467451
-Node: Auto-set475218
-Ref: Auto-set-Footnote-1492025
-Ref: Auto-set-Footnote-2492231
-Node: ARGC and ARGV492287
-Node: Pattern Action Summary496500
-Node: Arrays498930
-Node: Array Basics500259
-Node: Array Intro501103
-Ref: figure-array-elements503078
-Ref: Array Intro-Footnote-1505782
-Node: Reference to Elements505910
-Node: Assigning Elements508374
-Node: Array Example508865
-Node: Scanning an Array510624
-Node: Controlling Scanning513646
-Ref: Controlling Scanning-Footnote-1520102
-Node: Numeric Array Subscripts520418
-Node: Uninitialized Subscripts522602
-Node: Delete524221
-Ref: Delete-Footnote-1526973
-Node: Multidimensional527030
-Node: Multiscanning530125
-Node: Arrays of Arrays531716
-Node: Arrays Summary536484
-Node: Functions538577
-Node: Built-in539615
-Node: Calling Built-in540696
-Node: Numeric Functions542692
-Ref: Numeric Functions-Footnote-1546718
-Ref: Numeric Functions-Footnote-2547366
-Ref: Numeric Functions-Footnote-3547414
-Node: String Functions547686
-Ref: String Functions-Footnote-1571827
-Ref: String Functions-Footnote-2571955
-Ref: String Functions-Footnote-3572203
-Node: Gory Details572290
-Ref: table-sub-escapes574081
-Ref: table-sub-proposed575600
-Ref: table-posix-sub576963
-Ref: table-gensub-escapes578504
-Ref: Gory Details-Footnote-1579327
-Node: I/O Functions579481
-Ref: table-system-return-values585935
-Ref: I/O Functions-Footnote-1588015
-Ref: I/O Functions-Footnote-2588163
-Node: Time Functions588283
-Ref: Time Functions-Footnote-1598954
-Ref: Time Functions-Footnote-2599022
-Ref: Time Functions-Footnote-3599180
-Ref: Time Functions-Footnote-4599291
-Ref: Time Functions-Footnote-5599403
-Ref: Time Functions-Footnote-6599630
-Node: Bitwise Functions599896
-Ref: table-bitwise-ops600490
-Ref: Bitwise Functions-Footnote-1606553
-Ref: Bitwise Functions-Footnote-2606726
-Node: Type Functions606917
-Node: I18N Functions609780
-Node: User-defined611431
-Node: Definition Syntax612243
-Ref: Definition Syntax-Footnote-1617937
-Node: Function Example618008
-Ref: Function Example-Footnote-1620930
-Node: Function Calling620952
-Node: Calling A Function621540
-Node: Variable Scope622498
-Node: Pass By Value/Reference625492
-Node: Function Caveats628136
-Ref: Function Caveats-Footnote-1630183
-Node: Return Statement630303
-Node: Dynamic Typing633282
-Node: Indirect Calls634212
-Ref: Indirect Calls-Footnote-1644464
-Node: Functions Summary644592
-Node: Library Functions647297
-Ref: Library Functions-Footnote-1650904
-Ref: Library Functions-Footnote-2651047
-Node: Library Names651218
-Ref: Library Names-Footnote-1654885
-Ref: Library Names-Footnote-2655108
-Node: General Functions655194
-Node: Strtonum Function656297
-Node: Assert Function659319
-Node: Round Function662645
-Node: Cliff Random Function664185
-Node: Ordinal Functions665201
-Ref: Ordinal Functions-Footnote-1668264
-Ref: Ordinal Functions-Footnote-2668516
-Node: Join Function668726
-Ref: Join Function-Footnote-1670496
-Node: Getlocaltime Function670696
-Node: Readfile Function674438
-Node: Shell Quoting676415
-Node: Data File Management677816
-Node: Filetrans Function678448
-Node: Rewind Function682544
-Node: File Checking684453
-Ref: File Checking-Footnote-1685787
-Node: Empty Files685988
-Node: Ignoring Assigns687967
-Node: Getopt Function689517
-Ref: Getopt Function-Footnote-1704728
-Node: Passwd Functions704928
-Ref: Passwd Functions-Footnote-1713767
-Node: Group Functions713855
-Ref: Group Functions-Footnote-1721753
-Node: Walking Arrays721960
-Node: Library Functions Summary724968
-Node: Library Exercises726374
-Node: Sample Programs726839
-Node: Running Examples727609
-Node: Clones728337
-Node: Cut Program729561
-Node: Egrep Program739701
-Node: Id Program748712
-Node: Split Program758659
-Ref: Split Program-Footnote-1768549
-Node: Tee Program768722
-Node: Uniq Program771512
-Node: Wc Program779100
-Node: Bytes vs. Characters779497
-Node: Using extensions781045
-Node: wc program781799
-Node: Miscellaneous Programs786664
-Node: Dupword Program787877
-Node: Alarm Program789907
-Node: Translate Program794762
-Ref: Translate Program-Footnote-1799327
-Node: Labels Program799597
-Ref: Labels Program-Footnote-1802948
-Node: Word Sorting803032
-Node: History Sorting807104
-Node: Extract Program809329
-Node: Simple Sed817383
-Node: Igawk Program820457
-Ref: Igawk Program-Footnote-1834788
-Ref: Igawk Program-Footnote-2834990
-Ref: Igawk Program-Footnote-3835112
-Node: Anagram Program835227
-Node: Signature Program838289
-Node: Programs Summary839536
-Node: Programs Exercises840750
-Ref: Programs Exercises-Footnote-1844880
-Node: Advanced Features844966
-Node: Nondecimal Data847033
-Node: Array Sorting848624
-Node: Controlling Array Traversal849324
-Ref: Controlling Array Traversal-Footnote-1857692
-Node: Array Sorting Functions857810
-Ref: Array Sorting Functions-Footnote-1862901
-Node: Two-way I/O863097
-Ref: Two-way I/O-Footnote-1870818
-Ref: Two-way I/O-Footnote-2871005
-Node: TCP/IP Networking871087
-Node: Profiling874205
-Node: Extension Philosophy883514
-Node: Advanced Features Summary884965
-Node: Internationalization886964
-Node: I18N and L10N888444
-Node: Explaining gettext889131
-Ref: Explaining gettext-Footnote-1895023
-Ref: Explaining gettext-Footnote-2895208
-Node: Programmer i18n895373
-Ref: Programmer i18n-Footnote-1900322
-Node: Translator i18n900371
-Node: String Extraction901165
-Ref: String Extraction-Footnote-1902297
-Node: Printf Ordering902383
-Ref: Printf Ordering-Footnote-1905169
-Node: I18N Portability905233
-Ref: I18N Portability-Footnote-1907689
-Node: I18N Example907752
-Ref: I18N Example-Footnote-1911027
-Ref: I18N Example-Footnote-2911100
-Node: Gawk I18N911209
-Node: I18N Summary911858
-Node: Debugger913199
-Node: Debugging914199
-Node: Debugging Concepts914640
-Node: Debugging Terms916449
-Node: Awk Debugging919024
-Ref: Awk Debugging-Footnote-1919969
-Node: Sample Debugging Session920101
-Node: Debugger Invocation920635
-Node: Finding The Bug922021
-Node: List of Debugger Commands928495
-Node: Breakpoint Control929828
-Node: Debugger Execution Control933522
-Node: Viewing And Changing Data936884
-Node: Execution Stack940425
-Node: Debugger Info942062
-Node: Miscellaneous Debugger Commands946133
-Node: Readline Support951195
-Node: Limitations952091
-Node: Debugging Summary954645
-Node: Namespaces955924
-Node: Global Namespace957035
-Node: Qualified Names958433
-Node: Default Namespace959432
-Node: Changing The Namespace960173
-Node: Naming Rules961787
-Node: Internal Name Management963635
-Node: Namespace Example964677
-Node: Namespace And Features967239
-Node: Namespace Summary968674
-Node: Arbitrary Precision Arithmetic970151
-Node: Computer Arithmetic971638
-Ref: table-numeric-ranges975404
-Ref: table-floating-point-ranges975897
-Ref: Computer Arithmetic-Footnote-1976555
-Node: Math Definitions976612
-Ref: table-ieee-formats979588
-Node: MPFR features980155
-Node: FP Math Caution981873
-Ref: FP Math Caution-Footnote-1982945
-Node: Inexactness of computations983314
-Node: Inexact representation984345
-Node: Comparing FP Values985705
-Node: Errors accumulate986946
-Node: Strange values988402
-Ref: Strange values-Footnote-1990990
-Node: Getting Accuracy991095
-Node: Try To Round993805
-Node: Setting precision994704
-Ref: table-predefined-precision-strings995401
-Node: Setting the rounding mode997231
-Ref: table-gawk-rounding-modes997605
-Ref: Setting the rounding mode-Footnote-11001536
-Node: Arbitrary Precision Integers1001715
-Ref: Arbitrary Precision Integers-Footnote-11004890
-Node: Checking for MPFR1005039
-Node: POSIX Floating Point Problems1006513
-Ref: POSIX Floating Point Problems-Footnote-11010798
-Node: Floating point summary1010836
-Node: Dynamic Extensions1013026
-Node: Extension Intro1014579
-Node: Plugin License1015845
-Node: Extension Mechanism Outline1016642
-Ref: figure-load-extension1017081
-Ref: figure-register-new-function1018646
-Ref: figure-call-new-function1019738
-Node: Extension API Description1021800
-Node: Extension API Functions Introduction1023513
-Ref: table-api-std-headers1025349
-Node: General Data Types1029598
-Ref: General Data Types-Footnote-11038228
-Node: Memory Allocation Functions1038527
-Ref: Memory Allocation Functions-Footnote-11043028
-Node: Constructor Functions1043127
-Node: API Ownership of MPFR and GMP Values1046593
-Node: Registration Functions1047906
-Node: Extension Functions1048606
-Node: Exit Callback Functions1053928
-Node: Extension Version String1055178
-Node: Input Parsers1055841
-Node: Output Wrappers1068562
-Node: Two-way processors1073074
-Node: Printing Messages1075339
-Ref: Printing Messages-Footnote-11076510
-Node: Updating ERRNO1076663
-Node: Requesting Values1077402
-Ref: table-value-types-returned1078139
-Node: Accessing Parameters1079075
-Node: Symbol Table Access1080312
-Node: Symbol table by name1080824
-Ref: Symbol table by name-Footnote-11083848
-Node: Symbol table by cookie1083976
-Ref: Symbol table by cookie-Footnote-11088161
-Node: Cached values1088225
-Ref: Cached values-Footnote-11091761
-Node: Array Manipulation1091914
-Ref: Array Manipulation-Footnote-11093005
-Node: Array Data Types1093042
-Ref: Array Data Types-Footnote-11095700
-Node: Array Functions1095792
-Node: Flattening Arrays1100290
-Node: Creating Arrays1107266
-Node: Redirection API1112033
-Node: Extension API Variables1114866
-Node: Extension Versioning1115577
-Ref: gawk-api-version1116006
-Node: Extension GMP/MPFR Versioning1117737
-Node: Extension API Informational Variables1119365
-Node: Extension API Boilerplate1120438
-Node: Changes from API V11124412
-Node: Finding Extensions1125984
-Node: Extension Example1126543
-Node: Internal File Description1127341
-Node: Internal File Ops1131421
-Ref: Internal File Ops-Footnote-11142771
-Node: Using Internal File Ops1142911
-Ref: Using Internal File Ops-Footnote-11145294
-Node: Extension Samples1145568
-Node: Extension Sample File Functions1147097
-Node: Extension Sample Fnmatch1154746
-Node: Extension Sample Fork1156233
-Node: Extension Sample Inplace1157451
-Node: Extension Sample Ord1161077
-Node: Extension Sample Readdir1161913
-Ref: table-readdir-file-types1162802
-Node: Extension Sample Revout1163869
-Node: Extension Sample Rev2way1164458
-Node: Extension Sample Read write array1165198
-Node: Extension Sample Readfile1167140
-Node: Extension Sample Time1168235
-Node: Extension Sample API Tests1169987
-Node: gawkextlib1170479
-Node: Extension summary1173397
-Node: Extension Exercises1177099
-Node: Language History1178341
-Node: V7/SVR3.11179997
-Node: SVR41182149
-Node: POSIX1183583
-Node: BTL1184964
-Node: POSIX/GNU1185693
-Node: Feature History1191471
-Node: Common Extensions1207790
-Node: Ranges and Locales1209073
-Ref: Ranges and Locales-Footnote-11213689
-Ref: Ranges and Locales-Footnote-21213716
-Ref: Ranges and Locales-Footnote-31213951
-Node: Contributors1214174
-Node: History summary1220171
-Node: Installation1221551
-Node: Gawk Distribution1222495
-Node: Getting1222979
-Node: Extracting1223942
-Node: Distribution contents1225580
-Node: Unix Installation1232060
-Node: Quick Installation1232742
-Node: Shell Startup Files1235156
-Node: Additional Configuration Options1236245
-Node: Configuration Philosophy1238560
-Node: Non-Unix Installation1240929
-Node: PC Installation1241389
-Node: PC Binary Installation1242227
-Node: PC Compiling1242662
-Node: PC Using1243779
-Node: Cygwin1247332
-Node: MSYS1248556
-Node: VMS Installation1249158
-Node: VMS Compilation1249949
-Ref: VMS Compilation-Footnote-11251178
-Node: VMS Dynamic Extensions1251236
-Node: VMS Installation Details1252921
-Node: VMS Running1255174
-Node: VMS GNV1259453
-Node: VMS Old Gawk1260188
-Node: Bugs1260659
-Node: Bug address1261322
-Node: Usenet1264304
-Node: Maintainers1265308
-Node: Other Versions1266493
-Node: Installation summary1273581
-Node: Notes1274790
-Node: Compatibility Mode1275584
-Node: Additions1276366
-Node: Accessing The Source1277291
-Node: Adding Code1278728
-Node: New Ports1284947
-Node: Derived Files1289322
-Ref: Derived Files-Footnote-11294982
-Ref: Derived Files-Footnote-21295017
-Ref: Derived Files-Footnote-31295615
-Node: Future Extensions1295729
-Node: Implementation Limitations1296387
-Node: Extension Design1297597
-Node: Old Extension Problems1298741
-Ref: Old Extension Problems-Footnote-11300259
-Node: Extension New Mechanism Goals1300316
-Ref: Extension New Mechanism Goals-Footnote-11303680
-Node: Extension Other Design Decisions1303869
-Node: Extension Future Growth1305982
-Node: Notes summary1306588
-Node: Basic Concepts1307746
-Node: Basic High Level1308427
-Ref: figure-general-flow1308709
-Ref: figure-process-flow1309394
-Ref: Basic High Level-Footnote-11312695
-Node: Basic Data Typing1312880
-Node: Glossary1316208
-Node: Copying1348093
-Node: GNU Free Documentation License1385636
-Node: Index1410756
+Ref: gawk split records-Footnote-1214117
+Node: Fields214154
+Node: Nonconstant Fields216895
+Ref: Nonconstant Fields-Footnote-1219131
+Node: Changing Fields219335
+Node: Field Separators225366
+Node: Default Field Splitting228064
+Node: Regexp Field Splitting229182
+Node: Single Character Fields232859
+Node: Command Line Field Separator233919
+Node: Full Line Fields237137
+Ref: Full Line Fields-Footnote-1238659
+Ref: Full Line Fields-Footnote-2238705
+Node: Field Splitting Summary238806
+Node: Constant Size240880
+Node: Fixed width data241612
+Node: Skipping intervening245079
+Node: Allowing trailing data245877
+Node: Fields with fixed data246914
+Node: Splitting By Content248432
+Ref: Splitting By Content-Footnote-1252215
+Node: More CSV252378
+Node: Testing field creation253970
+Node: Multiple Line255595
+Node: Getline261872
+Node: Plain Getline264341
+Node: Getline/Variable266914
+Node: Getline/File268065
+Node: Getline/Variable/File269453
+Ref: Getline/Variable/File-Footnote-1271058
+Node: Getline/Pipe271146
+Node: Getline/Variable/Pipe273850
+Node: Getline/Coprocess274985
+Node: Getline/Variable/Coprocess276252
+Node: Getline Notes276994
+Node: Getline Summary279791
+Ref: table-getline-variants280215
+Node: Read Timeout280963
+Ref: Read Timeout-Footnote-1284869
+Node: Retrying Input284927
+Node: Command-line directories286126
+Node: Input Summary287032
+Node: Input Exercises290204
+Node: Printing290638
+Node: Print292472
+Node: Print Examples293929
+Node: Output Separators296709
+Node: OFMT298726
+Node: Printf300082
+Node: Basic Printf300867
+Node: Control Letters302441
+Node: Format Modifiers307603
+Node: Printf Examples313618
+Node: Redirection316104
+Node: Special FD322945
+Ref: Special FD-Footnote-1326113
+Node: Special Files326187
+Node: Other Inherited Files326804
+Node: Special Network327805
+Node: Special Caveats328665
+Node: Close Files And Pipes329614
+Ref: table-close-pipe-return-values336521
+Ref: Close Files And Pipes-Footnote-1337334
+Ref: Close Files And Pipes-Footnote-2337482
+Node: Nonfatal337634
+Node: Output Summary339972
+Node: Output Exercises341194
+Node: Expressions341873
+Node: Values343061
+Node: Constants343739
+Node: Scalar Constants344430
+Ref: Scalar Constants-Footnote-1346940
+Node: Nondecimal-numbers347190
+Node: Regexp Constants350191
+Node: Using Constant Regexps350717
+Node: Standard Regexp Constants351339
+Node: Strong Regexp Constants354527
+Node: Variables357539
+Node: Using Variables358196
+Node: Assignment Options360106
+Node: Conversion362577
+Node: Strings And Numbers363101
+Ref: Strings And Numbers-Footnote-1366164
+Node: Locale influences conversions366273
+Ref: table-locale-affects369031
+Node: All Operators369649
+Node: Arithmetic Ops370278
+Node: Concatenation372994
+Ref: Concatenation-Footnote-1375841
+Node: Assignment Ops375948
+Ref: table-assign-ops380939
+Node: Increment Ops382252
+Node: Truth Values and Conditions385712
+Node: Truth Values386786
+Node: Typing and Comparison387834
+Node: Variable Typing388654
+Ref: Variable Typing-Footnote-1395117
+Ref: Variable Typing-Footnote-2395189
+Node: Comparison Operators395266
+Ref: table-relational-ops395685
+Node: POSIX String Comparison399180
+Ref: POSIX String Comparison-Footnote-1400875
+Ref: POSIX String Comparison-Footnote-2401014
+Node: Boolean Ops401098
+Ref: Boolean Ops-Footnote-1405580
+Node: Conditional Exp405672
+Node: Function Calls407408
+Node: Precedence411285
+Node: Locales414944
+Node: Expressions Summary416576
+Node: Patterns and Actions419149
+Node: Pattern Overview420269
+Node: Regexp Patterns421946
+Node: Expression Patterns422488
+Node: Ranges426269
+Node: BEGIN/END429377
+Node: Using BEGIN/END430138
+Ref: Using BEGIN/END-Footnote-1432892
+Node: I/O And BEGIN/END432998
+Node: BEGINFILE/ENDFILE435311
+Node: Empty438542
+Node: Using Shell Variables438859
+Node: Action Overview441133
+Node: Statements443458
+Node: If Statement445306
+Node: While Statement446801
+Node: Do Statement448829
+Node: For Statement449977
+Node: Switch Statement453148
+Node: Break Statement455589
+Node: Continue Statement457681
+Node: Next Statement459508
+Node: Nextfile Statement461891
+Node: Exit Statement464580
+Node: Built-in Variables466983
+Node: User-modified468116
+Node: Auto-set475883
+Ref: Auto-set-Footnote-1492690
+Ref: Auto-set-Footnote-2492896
+Node: ARGC and ARGV492952
+Node: Pattern Action Summary497165
+Node: Arrays499595
+Node: Array Basics500924
+Node: Array Intro501768
+Ref: figure-array-elements503743
+Ref: Array Intro-Footnote-1506447
+Node: Reference to Elements506575
+Node: Assigning Elements509039
+Node: Array Example509530
+Node: Scanning an Array511289
+Node: Controlling Scanning514311
+Ref: Controlling Scanning-Footnote-1520767
+Node: Numeric Array Subscripts521083
+Node: Uninitialized Subscripts523267
+Node: Delete524886
+Ref: Delete-Footnote-1527638
+Node: Multidimensional527695
+Node: Multiscanning530790
+Node: Arrays of Arrays532381
+Node: Arrays Summary537149
+Node: Functions539242
+Node: Built-in540280
+Node: Calling Built-in541361
+Node: Numeric Functions543357
+Ref: Numeric Functions-Footnote-1547383
+Ref: Numeric Functions-Footnote-2548031
+Ref: Numeric Functions-Footnote-3548079
+Node: String Functions548351
+Ref: String Functions-Footnote-1572492
+Ref: String Functions-Footnote-2572620
+Ref: String Functions-Footnote-3572868
+Node: Gory Details572955
+Ref: table-sub-escapes574746
+Ref: table-sub-proposed576265
+Ref: table-posix-sub577628
+Ref: table-gensub-escapes579169
+Ref: Gory Details-Footnote-1579992
+Node: I/O Functions580146
+Ref: table-system-return-values586600
+Ref: I/O Functions-Footnote-1588680
+Ref: I/O Functions-Footnote-2588828
+Node: Time Functions588948
+Ref: Time Functions-Footnote-1599619
+Ref: Time Functions-Footnote-2599687
+Ref: Time Functions-Footnote-3599845
+Ref: Time Functions-Footnote-4599956
+Ref: Time Functions-Footnote-5600068
+Ref: Time Functions-Footnote-6600295
+Node: Bitwise Functions600561
+Ref: table-bitwise-ops601155
+Ref: Bitwise Functions-Footnote-1607218
+Ref: Bitwise Functions-Footnote-2607391
+Node: Type Functions607582
+Node: I18N Functions610445
+Node: User-defined612096
+Node: Definition Syntax612908
+Ref: Definition Syntax-Footnote-1618602
+Node: Function Example618673
+Ref: Function Example-Footnote-1621595
+Node: Function Calling621617
+Node: Calling A Function622205
+Node: Variable Scope623163
+Node: Pass By Value/Reference626157
+Node: Function Caveats628801
+Ref: Function Caveats-Footnote-1630848
+Node: Return Statement630968
+Node: Dynamic Typing633947
+Node: Indirect Calls634877
+Ref: Indirect Calls-Footnote-1645129
+Node: Functions Summary645257
+Node: Library Functions647962
+Ref: Library Functions-Footnote-1651569
+Ref: Library Functions-Footnote-2651712
+Node: Library Names651883
+Ref: Library Names-Footnote-1655550
+Ref: Library Names-Footnote-2655773
+Node: General Functions655859
+Node: Strtonum Function656962
+Node: Assert Function659984
+Node: Round Function663310
+Node: Cliff Random Function664850
+Node: Ordinal Functions665866
+Ref: Ordinal Functions-Footnote-1668929
+Ref: Ordinal Functions-Footnote-2669181
+Node: Join Function669391
+Ref: Join Function-Footnote-1671161
+Node: Getlocaltime Function671361
+Node: Readfile Function675103
+Node: Shell Quoting677080
+Node: Data File Management678481
+Node: Filetrans Function679113
+Node: Rewind Function683209
+Node: File Checking685118
+Ref: File Checking-Footnote-1686452
+Node: Empty Files686653
+Node: Ignoring Assigns688632
+Node: Getopt Function690182
+Ref: Getopt Function-Footnote-1705393
+Node: Passwd Functions705593
+Ref: Passwd Functions-Footnote-1714432
+Node: Group Functions714520
+Ref: Group Functions-Footnote-1722418
+Node: Walking Arrays722625
+Node: Library Functions Summary725633
+Node: Library Exercises727039
+Node: Sample Programs727504
+Node: Running Examples728274
+Node: Clones729002
+Node: Cut Program730226
+Node: Egrep Program740366
+Node: Id Program749377
+Node: Split Program759324
+Ref: Split Program-Footnote-1769214
+Node: Tee Program769387
+Node: Uniq Program772177
+Node: Wc Program779765
+Node: Bytes vs. Characters780162
+Node: Using extensions781710
+Node: wc program782464
+Node: Miscellaneous Programs787329
+Node: Dupword Program788542
+Node: Alarm Program790572
+Node: Translate Program795427
+Ref: Translate Program-Footnote-1799992
+Node: Labels Program800262
+Ref: Labels Program-Footnote-1803613
+Node: Word Sorting803697
+Node: History Sorting807769
+Node: Extract Program809994
+Node: Simple Sed818048
+Node: Igawk Program821122
+Ref: Igawk Program-Footnote-1835453
+Ref: Igawk Program-Footnote-2835655
+Ref: Igawk Program-Footnote-3835777
+Node: Anagram Program835892
+Node: Signature Program838954
+Node: Programs Summary840201
+Node: Programs Exercises841415
+Ref: Programs Exercises-Footnote-1845545
+Node: Advanced Features845631
+Node: Nondecimal Data847698
+Node: Array Sorting849289
+Node: Controlling Array Traversal849989
+Ref: Controlling Array Traversal-Footnote-1858357
+Node: Array Sorting Functions858475
+Ref: Array Sorting Functions-Footnote-1863566
+Node: Two-way I/O863762
+Ref: Two-way I/O-Footnote-1871483
+Ref: Two-way I/O-Footnote-2871670
+Node: TCP/IP Networking871752
+Node: Profiling874870
+Node: Extension Philosophy884179
+Node: Advanced Features Summary885630
+Node: Internationalization887629
+Node: I18N and L10N889109
+Node: Explaining gettext889796
+Ref: Explaining gettext-Footnote-1895688
+Ref: Explaining gettext-Footnote-2895873
+Node: Programmer i18n896038
+Ref: Programmer i18n-Footnote-1900987
+Node: Translator i18n901036
+Node: String Extraction901830
+Ref: String Extraction-Footnote-1902962
+Node: Printf Ordering903048
+Ref: Printf Ordering-Footnote-1905834
+Node: I18N Portability905898
+Ref: I18N Portability-Footnote-1908354
+Node: I18N Example908417
+Ref: I18N Example-Footnote-1911692
+Ref: I18N Example-Footnote-2911765
+Node: Gawk I18N911874
+Node: I18N Summary912523
+Node: Debugger913864
+Node: Debugging914864
+Node: Debugging Concepts915305
+Node: Debugging Terms917114
+Node: Awk Debugging919689
+Ref: Awk Debugging-Footnote-1920634
+Node: Sample Debugging Session920766
+Node: Debugger Invocation921300
+Node: Finding The Bug922686
+Node: List of Debugger Commands929160
+Node: Breakpoint Control930493
+Node: Debugger Execution Control934187
+Node: Viewing And Changing Data937549
+Node: Execution Stack941090
+Node: Debugger Info942727
+Node: Miscellaneous Debugger Commands946798
+Node: Readline Support951860
+Node: Limitations952756
+Node: Debugging Summary955310
+Node: Namespaces956589
+Node: Global Namespace957700
+Node: Qualified Names959098
+Node: Default Namespace960097
+Node: Changing The Namespace960838
+Node: Naming Rules962452
+Node: Internal Name Management964300
+Node: Namespace Example965342
+Node: Namespace And Features967904
+Node: Namespace Summary969339
+Node: Arbitrary Precision Arithmetic970816
+Node: Computer Arithmetic972303
+Ref: table-numeric-ranges976069
+Ref: table-floating-point-ranges976562
+Ref: Computer Arithmetic-Footnote-1977220
+Node: Math Definitions977277
+Ref: table-ieee-formats980253
+Node: MPFR features980820
+Node: FP Math Caution982538
+Ref: FP Math Caution-Footnote-1983610
+Node: Inexactness of computations983979
+Node: Inexact representation985010
+Node: Comparing FP Values986370
+Node: Errors accumulate987611
+Node: Strange values989067
+Ref: Strange values-Footnote-1991655
+Node: Getting Accuracy991760
+Node: Try To Round994470
+Node: Setting precision995369
+Ref: table-predefined-precision-strings996066
+Node: Setting the rounding mode997896
+Ref: table-gawk-rounding-modes998270
+Ref: Setting the rounding mode-Footnote-11002201
+Node: Arbitrary Precision Integers1002380
+Ref: Arbitrary Precision Integers-Footnote-11005555
+Node: Checking for MPFR1005704
+Node: POSIX Floating Point Problems1007178
+Ref: POSIX Floating Point Problems-Footnote-11011463
+Node: Floating point summary1011501
+Node: Dynamic Extensions1013691
+Node: Extension Intro1015244
+Node: Plugin License1016510
+Node: Extension Mechanism Outline1017307
+Ref: figure-load-extension1017746
+Ref: figure-register-new-function1019311
+Ref: figure-call-new-function1020403
+Node: Extension API Description1022465
+Node: Extension API Functions Introduction1024178
+Ref: table-api-std-headers1026014
+Node: General Data Types1030263
+Ref: General Data Types-Footnote-11038893
+Node: Memory Allocation Functions1039192
+Ref: Memory Allocation Functions-Footnote-11043693
+Node: Constructor Functions1043792
+Node: API Ownership of MPFR and GMP Values1047258
+Node: Registration Functions1048571
+Node: Extension Functions1049271
+Node: Exit Callback Functions1054593
+Node: Extension Version String1055843
+Node: Input Parsers1056506
+Node: Output Wrappers1069227
+Node: Two-way processors1073739
+Node: Printing Messages1076004
+Ref: Printing Messages-Footnote-11077175
+Node: Updating ERRNO1077328
+Node: Requesting Values1078067
+Ref: table-value-types-returned1078804
+Node: Accessing Parameters1079740
+Node: Symbol Table Access1080977
+Node: Symbol table by name1081489
+Ref: Symbol table by name-Footnote-11084513
+Node: Symbol table by cookie1084641
+Ref: Symbol table by cookie-Footnote-11088826
+Node: Cached values1088890
+Ref: Cached values-Footnote-11092426
+Node: Array Manipulation1092579
+Ref: Array Manipulation-Footnote-11093670
+Node: Array Data Types1093707
+Ref: Array Data Types-Footnote-11096365
+Node: Array Functions1096457
+Node: Flattening Arrays1100955
+Node: Creating Arrays1107931
+Node: Redirection API1112698
+Node: Extension API Variables1115531
+Node: Extension Versioning1116242
+Ref: gawk-api-version1116671
+Node: Extension GMP/MPFR Versioning1118402
+Node: Extension API Informational Variables1120030
+Node: Extension API Boilerplate1121103
+Node: Changes from API V11125077
+Node: Finding Extensions1126649
+Node: Extension Example1127208
+Node: Internal File Description1128006
+Node: Internal File Ops1132086
+Ref: Internal File Ops-Footnote-11143436
+Node: Using Internal File Ops1143576
+Ref: Using Internal File Ops-Footnote-11145959
+Node: Extension Samples1146233
+Node: Extension Sample File Functions1147762
+Node: Extension Sample Fnmatch1155411
+Node: Extension Sample Fork1156898
+Node: Extension Sample Inplace1158116
+Node: Extension Sample Ord1161742
+Node: Extension Sample Readdir1162578
+Ref: table-readdir-file-types1163467
+Node: Extension Sample Revout1164534
+Node: Extension Sample Rev2way1165123
+Node: Extension Sample Read write array1165863
+Node: Extension Sample Readfile1167805
+Node: Extension Sample Time1168900
+Node: Extension Sample API Tests1170652
+Node: gawkextlib1171144
+Node: Extension summary1174062
+Node: Extension Exercises1177764
+Node: Language History1179006
+Node: V7/SVR3.11180662
+Node: SVR41182814
+Node: POSIX1184248
+Node: BTL1185629
+Node: POSIX/GNU1186358
+Node: Feature History1192136
+Node: Common Extensions1208455
+Node: Ranges and Locales1209738
+Ref: Ranges and Locales-Footnote-11214354
+Ref: Ranges and Locales-Footnote-21214381
+Ref: Ranges and Locales-Footnote-31214616
+Node: Contributors1214839
+Node: History summary1220836
+Node: Installation1222216
+Node: Gawk Distribution1223160
+Node: Getting1223644
+Node: Extracting1224607
+Node: Distribution contents1226245
+Node: Unix Installation1232725
+Node: Quick Installation1233407
+Node: Shell Startup Files1235821
+Node: Additional Configuration Options1236910
+Node: Configuration Philosophy1239225
+Node: Non-Unix Installation1241594
+Node: PC Installation1242054
+Node: PC Binary Installation1242892
+Node: PC Compiling1243327
+Node: PC Using1244444
+Node: Cygwin1247997
+Node: MSYS1249221
+Node: VMS Installation1249823
+Node: VMS Compilation1250614
+Ref: VMS Compilation-Footnote-11251843
+Node: VMS Dynamic Extensions1251901
+Node: VMS Installation Details1253586
+Node: VMS Running1255839
+Node: VMS GNV1260118
+Node: VMS Old Gawk1260853
+Node: Bugs1261324
+Node: Bug address1261987
+Node: Usenet1264969
+Node: Maintainers1265973
+Node: Other Versions1267158
+Node: Installation summary1274246
+Node: Notes1275455
+Node: Compatibility Mode1276249
+Node: Additions1277031
+Node: Accessing The Source1277956
+Node: Adding Code1279393
+Node: New Ports1285612
+Node: Derived Files1289987
+Ref: Derived Files-Footnote-11295647
+Ref: Derived Files-Footnote-21295682
+Ref: Derived Files-Footnote-31296280
+Node: Future Extensions1296394
+Node: Implementation Limitations1297052
+Node: Extension Design1298262
+Node: Old Extension Problems1299406
+Ref: Old Extension Problems-Footnote-11300924
+Node: Extension New Mechanism Goals1300981
+Ref: Extension New Mechanism Goals-Footnote-11304345
+Node: Extension Other Design Decisions1304534
+Node: Extension Future Growth1306647
+Node: Notes summary1307253
+Node: Basic Concepts1308411
+Node: Basic High Level1309092
+Ref: figure-general-flow1309374
+Ref: figure-process-flow1310059
+Ref: Basic High Level-Footnote-11313360
+Node: Basic Data Typing1313545
+Node: Glossary1316873
+Node: Copying1348758
+Node: GNU Free Documentation License1386301
+Node: Index1411421
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 664f9e70..078a0ec8 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 September, 2020
+@set UPDATE-MONTH January, 2021
 @set VERSION 5.1
 @set PATCHLEVEL 0
 
@@ -285,13 +285,13 @@ Fax: +1-617-542-2652
 Email: <email>gnu@@gnu.org</email>
 URL: <ulink url="https://www.gnu.org">https://www.gnu.org/</ulink></literallayout>
 
-<literallayout class="normal">Copyright &copy; 1989, 1991, 1992, 1993, 1996&ndash;2005, 2007, 2009&ndash;2020
+<literallayout class="normal">Copyright &copy; 1989, 1991, 1992, 1993, 1996&ndash;2005, 2007, 2009&ndash;2021
 Free Software Foundation, Inc.
 All Rights Reserved.</literallayout>
 @end docbook
 
 @ifnotdocbook
-Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2020 @*
+Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2021 @*
 Free Software Foundation, Inc.
 @end ifnotdocbook
 @sp 2
@@ -6995,7 +6995,36 @@ if the input text that could match the trailing part is fairly long.
 @command{gawk} attempts to avoid this problem, but currently, there's
 no guarantee that this will never happen.
 
-@quotation NOTE
+@cindex sidebar @subentry Caveats When Using Regular Expressions for @code{RS}
+@ifdocbook
+@docbook
+<sidebar><title>Caveats When Using Regular Expressions for @code{RS}</title>
+@end docbook
+
+Remember that in @command{awk}, the @samp{^} and @samp{$} anchor
+metacharacters match the beginning and end of a @emph{string}, and not
+the beginning and end of a @emph{line}.  As a result, something like
+@samp{RS = "^[[:upper:]]"} can only match at the beginning of a file.
+This is because @command{gawk} views the input file as one long string
+that happens to contain newline characters.
+It is thus best to avoid anchor metacharacters in the value of @code{RS}.
+
+Record splitting with regular expressions works differently than
+regexp matching with the @code{sub()}, @code{gsub()}, and @code{gensub()}
+(@pxref{String Functions}).  Those functions allow a regexp to match the empty string;
+record splitting does not.  Thus, for example @samp{RS = "()"} does @emph{not}
+split records between characters.
+
+@docbook
+</sidebar>
+@end docbook
+@end ifdocbook
+
+@ifnotdocbook
+@cartouche
+@center @b{Caveats When Using Regular Expressions for @code{RS}}
+
+
 Remember that in @command{awk}, the @samp{^} and @samp{$} anchor
 metacharacters match the beginning and end of a @emph{string}, and not
 the beginning and end of a @emph{line}.  As a result, something like
@@ -7003,7 +7032,14 @@ the beginning and end of a @emph{line}.  As a result, something like
 This is because @command{gawk} views the input file as one long string
 that happens to contain newline characters.
 It is thus best to avoid anchor metacharacters in the value of @code{RS}.
-@end quotation
+
+Record splitting with regular expressions works differently than
+regexp matching with the @code{sub()}, @code{gsub()}, and @code{gensub()}
+(@pxref{String Functions}).  Those functions allow a regexp to match the empty string;
+record splitting does not.  Thus, for example @samp{RS = "()"} does @emph{not}
+split records between characters.
+@end cartouche
+@end ifnotdocbook
 
 @cindex @command{gawk} @subentry @code{RT} variable in
 @cindex @code{RT} variable
@@ -7712,6 +7748,12 @@ $ @kbd{echo 'xxAA  xxBxx  C' |}
 @print{} -->C<--
 @end example
 
+Finally, field splitting with regular expressions works differently than
+regexp matching with the @code{sub()}, @code{gsub()}, and @code{gensub()}
+(@pxref{String Functions}).  Those functions allow a regexp to match the
+empty string; field splitting does not.  Thus, for example @samp{FS =
+"()"} does @emph{not} split fields between characters.
+
 @node Single Character Fields
 @subsection Making Each Character a Separate Field
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 92098829..78ad076d 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 September, 2020
+@set UPDATE-MONTH January, 2021
 @set VERSION 5.1
 @set PATCHLEVEL 0
 
@@ -280,13 +280,13 @@ Fax: +1-617-542-2652
 Email: <email>gnu@@gnu.org</email>
 URL: <ulink url="https://www.gnu.org">https://www.gnu.org/</ulink></literallayout>
 
-<literallayout class="normal">Copyright &copy; 1989, 1991, 1992, 1993, 1996&ndash;2005, 2007, 2009&ndash;2020
+<literallayout class="normal">Copyright &copy; 1989, 1991, 1992, 1993, 1996&ndash;2005, 2007, 2009&ndash;2021
 Free Software Foundation, Inc.
 All Rights Reserved.</literallayout>
 @end docbook
 
 @ifnotdocbook
-Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2020 @*
+Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2021 @*
 Free Software Foundation, Inc.
 @end ifnotdocbook
 @sp 2
@@ -6733,7 +6733,7 @@ if the input text that could match the trailing part is fairly long.
 @command{gawk} attempts to avoid this problem, but currently, there's
 no guarantee that this will never happen.
 
-@quotation NOTE
+@sidebar Caveats When Using Regular Expressions for @code{RS}
 Remember that in @command{awk}, the @samp{^} and @samp{$} anchor
 metacharacters match the beginning and end of a @emph{string}, and not
 the beginning and end of a @emph{line}.  As a result, something like
@@ -6741,7 +6741,13 @@ the beginning and end of a @emph{line}.  As a result, something like
 This is because @command{gawk} views the input file as one long string
 that happens to contain newline characters.
 It is thus best to avoid anchor metacharacters in the value of @code{RS}.
-@end quotation
+
+Record splitting with regular expressions works differently than
+regexp matching with the @code{sub()}, @code{gsub()}, and @code{gensub()}
+(@pxref{String Functions}).  Those functions allow a regexp to match the empty string;
+record splitting does not.  Thus, for example @samp{RS = "()"} does @emph{not}
+split records between characters.
+@end sidebar
 
 @cindex @command{gawk} @subentry @code{RT} variable in
 @cindex @code{RT} variable
@@ -7361,6 +7367,12 @@ $ @kbd{echo 'xxAA  xxBxx  C' |}
 @print{} -->C<--
 @end example
 
+Finally, field splitting with regular expressions works differently than
+regexp matching with the @code{sub()}, @code{gsub()}, and @code{gensub()}
+(@pxref{String Functions}).  Those functions allow a regexp to match the
+empty string; field splitting does not.  Thus, for example @samp{FS =
+"()"} does @emph{not} split fields between characters.
+
 @node Single Character Fields
 @subsection Making Each Character a Separate Field