Further improvement on discussion of RS.

4 files changed, 543 insertions, 519 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index d515ccc0..99abe070 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2018-06-12         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Records, gawk split records): More explanation
+	of how RS works when it's longer than one character. Thanks
+	to Andrew Schorr for most of the wording.
+
 2018-06-11         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.iin (awk split records): Document that even if the
diff --git a/doc/gawk.info b/doc/gawk.info
index 9c4ce333..29051f64 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -4281,6 +4281,12 @@ Another predefined variable, 'NR', records the total number of input
 records read so far from all data files.  It starts at zero, but is
 never automatically reset to zero.
 
+   Normally, records are separated by newline characters.  You can
+control how records are separated by assigning values to the built-in
+variable 'RS'.  If 'RS' is any single character, that character
+separates records.  Otherwise (in 'gawk'), 'RS' is treated as a regular
+expression.  This mechanism is explained in greater detail shortly.
+
 * Menu:
 
 * awk split records::           How standard 'awk' splits records.
@@ -4427,15 +4433,15 @@ File: gawk.info,  Node: gawk split records,  Prev: awk split records,  Up: Recor
 ----------------------------------
 
 When using 'gawk', the value of 'RS' is not limited to a one-character
-string.  It can be any regular expression (*note Regexp::).  (c.e.)  In
-general, each record ends at the next string that matches the regular
-expression; the next record starts at the end of the matching string.
-This general rule is actually at work in the usual case, where 'RS'
-contains just a newline: a record ends at the beginning of the next
-matching string (the next newline in the input), and the following
-record starts just after the end of this string (at the first character
-of the following line).  The newline, because it matches 'RS', is not
-part of either record.
+string.  If it contains more than one character, it is treated as a
+regular expression (*note Regexp::).  (c.e.)  In general, each record
+ends at the next string that matches the regular expression; the next
+record starts at the end of the matching string.  This general rule is
+actually at work in the usual case, where 'RS' contains just a newline:
+a record ends at the beginning of the next matching string (the next
+newline in the input), and the following record starts just after the
+end of this string (at the first character of the following line).  The
+newline, because it matches 'RS', is not part of either record.
 
    When 'RS' is a single character, 'RT' contains the same single
 character.  However, when 'RS' is a regular expression, 'RT' contains
@@ -36111,509 +36117,509 @@ Ref: Case-sensitivity-Footnote-2192147
 Node: Regexp Summary192255
 Node: Reading Files193721
 Node: Records195990
-Node: awk split records196723
-Node: gawk split records201998
-Ref: gawk split records-Footnote-1206538
-Node: Fields206575
-Node: Nonconstant Fields209316
-Ref: Nonconstant Fields-Footnote-1211552
-Node: Changing Fields211756
-Node: Field Separators217684
-Node: Default Field Splitting220382
-Node: Regexp Field Splitting221500
-Node: Single Character Fields224853
-Node: Command Line Field Separator225913
-Node: Full Line Fields229131
-Ref: Full Line Fields-Footnote-1230653
-Ref: Full Line Fields-Footnote-2230699
-Node: Field Splitting Summary230800
-Node: Constant Size232874
-Node: Fixed width data233606
-Node: Skipping intervening237073
-Node: Allowing trailing data237871
-Node: Fields with fixed data238908
-Node: Splitting By Content240426
-Ref: Splitting By Content-Footnote-1244076
-Node: Testing field creation244239
-Node: Multiple Line245864
-Ref: Multiple Line-Footnote-1251748
-Node: Getline251927
-Node: Plain Getline254396
-Node: Getline/Variable257037
-Node: Getline/File258188
-Node: Getline/Variable/File259576
-Ref: Getline/Variable/File-Footnote-1261181
-Node: Getline/Pipe261269
-Node: Getline/Variable/Pipe263976
-Node: Getline/Coprocess265111
-Node: Getline/Variable/Coprocess266378
-Node: Getline Notes267120
-Node: Getline Summary269917
-Ref: table-getline-variants270341
-Node: Read Timeout271089
-Ref: Read Timeout-Footnote-1274995
-Node: Retrying Input275053
-Node: Command-line directories276252
-Node: Input Summary277158
-Node: Input Exercises280330
-Node: Printing281058
-Node: Print282892
-Node: Print Examples284349
-Node: Output Separators287129
-Node: OFMT289146
-Node: Printf290502
-Node: Basic Printf291287
-Node: Control Letters292861
-Node: Format Modifiers297540
-Node: Printf Examples303555
-Node: Redirection306041
-Node: Special FD312882
-Ref: Special FD-Footnote-1316050
-Node: Special Files316124
-Node: Other Inherited Files316741
-Node: Special Network317742
-Node: Special Caveats318602
-Node: Close Files And Pipes319551
-Ref: table-close-pipe-return-values326458
-Ref: Close Files And Pipes-Footnote-1327271
-Ref: Close Files And Pipes-Footnote-2327419
-Node: Nonfatal327571
-Node: Output Summary329909
-Node: Output Exercises331131
-Node: Expressions331810
-Node: Values332998
-Node: Constants333676
-Node: Scalar Constants334367
-Ref: Scalar Constants-Footnote-1335231
-Node: Nondecimal-numbers335481
-Node: Regexp Constants338482
-Node: Using Constant Regexps339008
-Node: Standard Regexp Constants339630
-Node: Strong Regexp Constants342818
-Node: Variables345776
-Node: Using Variables346433
-Node: Assignment Options348343
-Node: Conversion350216
-Node: Strings And Numbers350740
-Ref: Strings And Numbers-Footnote-1353803
-Node: Locale influences conversions353912
-Ref: table-locale-affects356670
-Node: All Operators357288
-Node: Arithmetic Ops357917
-Node: Concatenation360423
-Ref: Concatenation-Footnote-1363270
-Node: Assignment Ops363377
-Ref: table-assign-ops368368
-Node: Increment Ops369681
-Node: Truth Values and Conditions373141
-Node: Truth Values374215
-Node: Typing and Comparison375263
-Node: Variable Typing376083
-Ref: Variable Typing-Footnote-1382546
-Ref: Variable Typing-Footnote-2382618
-Node: Comparison Operators382695
-Ref: table-relational-ops383114
-Node: POSIX String Comparison386609
-Ref: POSIX String Comparison-Footnote-1388304
-Ref: POSIX String Comparison-Footnote-2388443
-Node: Boolean Ops388527
-Ref: Boolean Ops-Footnote-1393009
-Node: Conditional Exp393101
-Node: Function Calls394837
-Node: Precedence398714
-Node: Locales402373
-Node: Expressions Summary404005
-Node: Patterns and Actions406578
-Node: Pattern Overview407698
-Node: Regexp Patterns409375
-Node: Expression Patterns409917
-Node: Ranges413698
-Node: BEGIN/END416806
-Node: Using BEGIN/END417567
-Ref: Using BEGIN/END-Footnote-1420303
-Node: I/O And BEGIN/END420409
-Node: BEGINFILE/ENDFILE422723
-Node: Empty425636
-Node: Using Shell Variables425953
-Node: Action Overview428227
-Node: Statements430552
-Node: If Statement432400
-Node: While Statement433895
-Node: Do Statement435923
-Node: For Statement437071
-Node: Switch Statement440242
-Node: Break Statement442628
-Node: Continue Statement444720
-Node: Next Statement446547
-Node: Nextfile Statement448930
-Node: Exit Statement451582
-Node: Built-in Variables453985
-Node: User-modified455118
-Node: Auto-set462885
-Ref: Auto-set-Footnote-1479187
-Ref: Auto-set-Footnote-2479393
-Node: ARGC and ARGV479449
-Node: Pattern Action Summary483662
-Node: Arrays486092
-Node: Array Basics487421
-Node: Array Intro488265
-Ref: figure-array-elements490240
-Ref: Array Intro-Footnote-1492944
-Node: Reference to Elements493072
-Node: Assigning Elements495536
-Node: Array Example496027
-Node: Scanning an Array497786
-Node: Controlling Scanning500808
-Ref: Controlling Scanning-Footnote-1506207
-Node: Numeric Array Subscripts506523
-Node: Uninitialized Subscripts508707
-Node: Delete510326
-Ref: Delete-Footnote-1513078
-Node: Multidimensional513135
-Node: Multiscanning516230
-Node: Arrays of Arrays517821
-Node: Arrays Summary522588
-Node: Functions524681
-Node: Built-in525719
-Node: Calling Built-in526800
-Node: Numeric Functions528796
-Ref: Numeric Functions-Footnote-1532824
-Ref: Numeric Functions-Footnote-2533181
-Ref: Numeric Functions-Footnote-3533229
-Node: String Functions533501
-Ref: String Functions-Footnote-1557210
-Ref: String Functions-Footnote-2557338
-Ref: String Functions-Footnote-3557586
-Node: Gory Details557673
-Ref: table-sub-escapes559464
-Ref: table-sub-proposed560983
-Ref: table-posix-sub562346
-Ref: table-gensub-escapes563887
-Ref: Gory Details-Footnote-1564710
-Node: I/O Functions564864
-Ref: table-system-return-values571332
-Ref: I/O Functions-Footnote-1573312
-Ref: I/O Functions-Footnote-2573460
-Node: Time Functions573580
-Ref: Time Functions-Footnote-1584251
-Ref: Time Functions-Footnote-2584319
-Ref: Time Functions-Footnote-3584477
-Ref: Time Functions-Footnote-4584588
-Ref: Time Functions-Footnote-5584700
-Ref: Time Functions-Footnote-6584927
-Node: Bitwise Functions585193
-Ref: table-bitwise-ops585787
-Ref: Bitwise Functions-Footnote-1591850
-Ref: Bitwise Functions-Footnote-2592023
-Node: Type Functions592214
-Node: I18N Functions594965
-Node: User-defined596616
-Node: Definition Syntax597421
-Ref: Definition Syntax-Footnote-1603108
-Node: Function Example603179
-Ref: Function Example-Footnote-1606101
-Node: Function Caveats606123
-Node: Calling A Function606641
-Node: Variable Scope607599
-Node: Pass By Value/Reference610593
-Node: Return Statement614092
-Node: Dynamic Typing617071
-Node: Indirect Calls618001
-Ref: Indirect Calls-Footnote-1628253
-Node: Functions Summary628381
-Node: Library Functions631086
-Ref: Library Functions-Footnote-1634693
-Ref: Library Functions-Footnote-2634836
-Node: Library Names635007
-Ref: Library Names-Footnote-1638467
-Ref: Library Names-Footnote-2638690
-Node: General Functions638776
-Node: Strtonum Function639879
-Node: Assert Function642901
-Node: Round Function646227
-Node: Cliff Random Function647767
-Node: Ordinal Functions648783
-Ref: Ordinal Functions-Footnote-1651846
-Ref: Ordinal Functions-Footnote-2652098
-Node: Join Function652308
-Ref: Join Function-Footnote-1654078
-Node: Getlocaltime Function654278
-Node: Readfile Function658020
-Node: Shell Quoting659997
-Node: Data File Management661398
-Node: Filetrans Function662030
-Node: Rewind Function666126
-Node: File Checking668036
-Ref: File Checking-Footnote-1669370
-Node: Empty Files669571
-Node: Ignoring Assigns671550
-Node: Getopt Function673100
-Ref: Getopt Function-Footnote-1684569
-Node: Passwd Functions684769
-Ref: Passwd Functions-Footnote-1693608
-Node: Group Functions693696
-Ref: Group Functions-Footnote-1701594
-Node: Walking Arrays701801
-Node: Library Functions Summary704809
-Node: Library Exercises706215
-Node: Sample Programs706680
-Node: Running Examples707450
-Node: Clones708178
-Node: Cut Program709402
-Node: Egrep Program719331
-Ref: Egrep Program-Footnote-1726843
-Node: Id Program726953
-Node: Split Program730633
-Ref: Split Program-Footnote-1734091
-Node: Tee Program734220
-Node: Uniq Program737010
-Node: Wc Program744436
-Ref: Wc Program-Footnote-1748691
-Node: Miscellaneous Programs748785
-Node: Dupword Program749998
-Node: Alarm Program752028
-Node: Translate Program756883
-Ref: Translate Program-Footnote-1761448
-Node: Labels Program761718
-Ref: Labels Program-Footnote-1765069
-Node: Word Sorting765153
-Node: History Sorting769225
-Node: Extract Program771060
-Node: Simple Sed779114
-Node: Igawk Program782188
-Ref: Igawk Program-Footnote-1796519
-Ref: Igawk Program-Footnote-2796721
-Ref: Igawk Program-Footnote-3796843
-Node: Anagram Program796958
-Node: Signature Program800020
-Node: Programs Summary801267
-Node: Programs Exercises802481
-Ref: Programs Exercises-Footnote-1806610
-Node: Advanced Features806701
-Node: Nondecimal Data808691
-Node: Array Sorting810282
-Node: Controlling Array Traversal810982
-Ref: Controlling Array Traversal-Footnote-1819350
-Node: Array Sorting Functions819468
-Ref: Array Sorting Functions-Footnote-1824559
-Node: Two-way I/O824755
-Ref: Two-way I/O-Footnote-1831307
-Ref: Two-way I/O-Footnote-2831494
-Node: TCP/IP Networking831576
-Node: Profiling834694
-Ref: Profiling-Footnote-1843366
-Node: Advanced Features Summary843689
-Node: Internationalization845533
-Node: I18N and L10N847013
-Node: Explaining gettext847700
-Ref: Explaining gettext-Footnote-1853592
-Ref: Explaining gettext-Footnote-2853777
-Node: Programmer i18n853942
-Ref: Programmer i18n-Footnote-1858891
-Node: Translator i18n858940
-Node: String Extraction859734
-Ref: String Extraction-Footnote-1860866
-Node: Printf Ordering860952
-Ref: Printf Ordering-Footnote-1863738
-Node: I18N Portability863802
-Ref: I18N Portability-Footnote-1866258
-Node: I18N Example866321
-Ref: I18N Example-Footnote-1869127
-Node: Gawk I18N869200
-Node: I18N Summary869845
-Node: Debugger871186
-Node: Debugging872209
-Node: Debugging Concepts872650
-Node: Debugging Terms874459
-Node: Awk Debugging877034
-Node: Sample Debugging Session877940
-Node: Debugger Invocation878474
-Node: Finding The Bug879860
-Node: List of Debugger Commands886338
-Node: Breakpoint Control887671
-Node: Debugger Execution Control891365
-Node: Viewing And Changing Data894727
-Node: Execution Stack898101
-Node: Debugger Info899738
-Node: Miscellaneous Debugger Commands903809
-Node: Readline Support908871
-Node: Limitations909767
-Node: Debugging Summary911876
-Node: Arbitrary Precision Arithmetic913155
-Node: Computer Arithmetic914640
-Ref: table-numeric-ranges918406
-Ref: table-floating-point-ranges918899
-Ref: Computer Arithmetic-Footnote-1919557
-Node: Math Definitions919614
-Ref: table-ieee-formats922930
-Ref: Math Definitions-Footnote-1923533
-Node: MPFR features923638
-Node: FP Math Caution925356
-Ref: FP Math Caution-Footnote-1926428
-Node: Inexactness of computations926797
-Node: Inexact representation927757
-Node: Comparing FP Values929117
-Node: Errors accumulate930199
-Node: Getting Accuracy931632
-Node: Try To Round934342
-Node: Setting precision935241
-Ref: table-predefined-precision-strings935938
-Node: Setting the rounding mode937768
-Ref: table-gawk-rounding-modes938142
-Ref: Setting the rounding mode-Footnote-1942073
-Node: Arbitrary Precision Integers942252
-Ref: Arbitrary Precision Integers-Footnote-1945427
-Node: Checking for MPFR945576
-Node: POSIX Floating Point Problems947050
-Ref: POSIX Floating Point Problems-Footnote-1950921
-Node: Floating point summary950959
-Node: Dynamic Extensions953149
-Node: Extension Intro954702
-Node: Plugin License955968
-Node: Extension Mechanism Outline956765
-Ref: figure-load-extension957204
-Ref: figure-register-new-function958769
-Ref: figure-call-new-function959861
-Node: Extension API Description961923
-Node: Extension API Functions Introduction963565
-Node: General Data Types969105
-Ref: General Data Types-Footnote-1977466
-Node: Memory Allocation Functions977765
-Ref: Memory Allocation Functions-Footnote-1981975
-Node: Constructor Functions982074
-Node: Registration Functions985660
-Node: Extension Functions986345
-Node: Exit Callback Functions991560
-Node: Extension Version String992810
-Node: Input Parsers993473
-Node: Output Wrappers1006194
-Node: Two-way processors1010706
-Node: Printing Messages1012971
-Ref: Printing Messages-Footnote-11014142
-Node: Updating ERRNO1014295
-Node: Requesting Values1015034
-Ref: table-value-types-returned1015771
-Node: Accessing Parameters1016707
-Node: Symbol Table Access1017942
-Node: Symbol table by name1018454
-Node: Symbol table by cookie1020243
-Ref: Symbol table by cookie-Footnote-11024428
-Node: Cached values1024492
-Ref: Cached values-Footnote-11028028
-Node: Array Manipulation1028181
-Ref: Array Manipulation-Footnote-11029272
-Node: Array Data Types1029309
-Ref: Array Data Types-Footnote-11031967
-Node: Array Functions1032059
-Node: Flattening Arrays1036557
-Node: Creating Arrays1043533
-Node: Redirection API1048300
-Node: Extension API Variables1051133
-Node: Extension Versioning1051844
-Ref: gawk-api-version1052273
-Node: Extension GMP/MPFR Versioning1054004
-Node: Extension API Informational Variables1055632
-Node: Extension API Boilerplate1056705
-Node: Changes from API V11060679
-Node: Finding Extensions1062251
-Node: Extension Example1062810
-Node: Internal File Description1063608
-Node: Internal File Ops1067688
-Ref: Internal File Ops-Footnote-11079038
-Node: Using Internal File Ops1079178
-Ref: Using Internal File Ops-Footnote-11081561
-Node: Extension Samples1081835
-Node: Extension Sample File Functions1083364
-Node: Extension Sample Fnmatch1091013
-Node: Extension Sample Fork1092500
-Node: Extension Sample Inplace1093718
-Node: Extension Sample Ord1096935
-Node: Extension Sample Readdir1097771
-Ref: table-readdir-file-types1098660
-Node: Extension Sample Revout1099465
-Node: Extension Sample Rev2way1100054
-Node: Extension Sample Read write array1100794
-Node: Extension Sample Readfile1102736
-Node: Extension Sample Time1103831
-Node: Extension Sample API Tests1105179
-Node: gawkextlib1105671
-Node: Extension summary1108589
-Node: Extension Exercises1112291
-Node: Language History1113789
-Node: V7/SVR3.11115445
-Node: SVR41117597
-Node: POSIX1119031
-Node: BTL1120411
-Node: POSIX/GNU1121140
-Node: Feature History1126918
-Node: Common Extensions1142777
-Node: Ranges and Locales1144060
-Ref: Ranges and Locales-Footnote-11148676
-Ref: Ranges and Locales-Footnote-21148703
-Ref: Ranges and Locales-Footnote-31148938
-Node: Contributors1149159
-Node: History summary1155104
-Node: Installation1156484
-Node: Gawk Distribution1157428
-Node: Getting1157912
-Node: Extracting1158875
-Node: Distribution contents1160513
-Node: Unix Installation1166993
-Node: Quick Installation1167675
-Node: Shell Startup Files1170089
-Node: Additional Configuration Options1171178
-Node: Configuration Philosophy1173471
-Node: Non-Unix Installation1175840
-Node: PC Installation1176300
-Node: PC Binary Installation1177138
-Node: PC Compiling1177573
-Node: PC Using1178690
-Node: Cygwin1181905
-Node: MSYS1183004
-Node: VMS Installation1183505
-Node: VMS Compilation1184296
-Ref: VMS Compilation-Footnote-11185525
-Node: VMS Dynamic Extensions1185583
-Node: VMS Installation Details1187268
-Node: VMS Running1189521
-Node: VMS GNV1193800
-Node: VMS Old Gawk1194535
-Node: Bugs1195006
-Node: Bug address1195669
-Node: Usenet1198461
-Node: Maintainers1199238
-Node: Other Versions1200499
-Node: Installation summary1207261
-Node: Notes1208463
-Node: Compatibility Mode1209328
-Node: Additions1210110
-Node: Accessing The Source1211035
-Node: Adding Code1212472
-Node: New Ports1218691
-Node: Derived Files1223179
-Ref: Derived Files-Footnote-11228825
-Ref: Derived Files-Footnote-21228860
-Ref: Derived Files-Footnote-31229458
-Node: Future Extensions1229572
-Node: Implementation Limitations1230230
-Node: Extension Design1231413
-Node: Old Extension Problems1232567
-Ref: Old Extension Problems-Footnote-11234085
-Node: Extension New Mechanism Goals1234142
-Ref: Extension New Mechanism Goals-Footnote-11237506
-Node: Extension Other Design Decisions1237695
-Node: Extension Future Growth1239808
-Node: Old Extension Mechanism1240644
-Node: Notes summary1242407
-Node: Basic Concepts1243589
-Node: Basic High Level1244270
-Ref: figure-general-flow1244552
-Ref: figure-process-flow1245237
-Ref: Basic High Level-Footnote-11248538
-Node: Basic Data Typing1248723
-Node: Glossary1252051
-Node: Copying1283889
-Node: GNU Free Documentation License1321432
-Node: Index1346552
+Node: awk split records197065
+Node: gawk split records202340
+Ref: gawk split records-Footnote-1206926
+Node: Fields206963
+Node: Nonconstant Fields209704
+Ref: Nonconstant Fields-Footnote-1211940
+Node: Changing Fields212144
+Node: Field Separators218072
+Node: Default Field Splitting220770
+Node: Regexp Field Splitting221888
+Node: Single Character Fields225241
+Node: Command Line Field Separator226301
+Node: Full Line Fields229519
+Ref: Full Line Fields-Footnote-1231041
+Ref: Full Line Fields-Footnote-2231087
+Node: Field Splitting Summary231188
+Node: Constant Size233262
+Node: Fixed width data233994
+Node: Skipping intervening237461
+Node: Allowing trailing data238259
+Node: Fields with fixed data239296
+Node: Splitting By Content240814
+Ref: Splitting By Content-Footnote-1244464
+Node: Testing field creation244627
+Node: Multiple Line246252
+Ref: Multiple Line-Footnote-1252136
+Node: Getline252315
+Node: Plain Getline254784
+Node: Getline/Variable257425
+Node: Getline/File258576
+Node: Getline/Variable/File259964
+Ref: Getline/Variable/File-Footnote-1261569
+Node: Getline/Pipe261657
+Node: Getline/Variable/Pipe264364
+Node: Getline/Coprocess265499
+Node: Getline/Variable/Coprocess266766
+Node: Getline Notes267508
+Node: Getline Summary270305
+Ref: table-getline-variants270729
+Node: Read Timeout271477
+Ref: Read Timeout-Footnote-1275383
+Node: Retrying Input275441
+Node: Command-line directories276640
+Node: Input Summary277546
+Node: Input Exercises280718
+Node: Printing281446
+Node: Print283280
+Node: Print Examples284737
+Node: Output Separators287517
+Node: OFMT289534
+Node: Printf290890
+Node: Basic Printf291675
+Node: Control Letters293249
+Node: Format Modifiers297928
+Node: Printf Examples303943
+Node: Redirection306429
+Node: Special FD313270
+Ref: Special FD-Footnote-1316438
+Node: Special Files316512
+Node: Other Inherited Files317129
+Node: Special Network318130
+Node: Special Caveats318990
+Node: Close Files And Pipes319939
+Ref: table-close-pipe-return-values326846
+Ref: Close Files And Pipes-Footnote-1327659
+Ref: Close Files And Pipes-Footnote-2327807
+Node: Nonfatal327959
+Node: Output Summary330297
+Node: Output Exercises331519
+Node: Expressions332198
+Node: Values333386
+Node: Constants334064
+Node: Scalar Constants334755
+Ref: Scalar Constants-Footnote-1335619
+Node: Nondecimal-numbers335869
+Node: Regexp Constants338870
+Node: Using Constant Regexps339396
+Node: Standard Regexp Constants340018
+Node: Strong Regexp Constants343206
+Node: Variables346164
+Node: Using Variables346821
+Node: Assignment Options348731
+Node: Conversion350604
+Node: Strings And Numbers351128
+Ref: Strings And Numbers-Footnote-1354191
+Node: Locale influences conversions354300
+Ref: table-locale-affects357058
+Node: All Operators357676
+Node: Arithmetic Ops358305
+Node: Concatenation360811
+Ref: Concatenation-Footnote-1363658
+Node: Assignment Ops363765
+Ref: table-assign-ops368756
+Node: Increment Ops370069
+Node: Truth Values and Conditions373529
+Node: Truth Values374603
+Node: Typing and Comparison375651
+Node: Variable Typing376471
+Ref: Variable Typing-Footnote-1382934
+Ref: Variable Typing-Footnote-2383006
+Node: Comparison Operators383083
+Ref: table-relational-ops383502
+Node: POSIX String Comparison386997
+Ref: POSIX String Comparison-Footnote-1388692
+Ref: POSIX String Comparison-Footnote-2388831
+Node: Boolean Ops388915
+Ref: Boolean Ops-Footnote-1393397
+Node: Conditional Exp393489
+Node: Function Calls395225
+Node: Precedence399102
+Node: Locales402761
+Node: Expressions Summary404393
+Node: Patterns and Actions406966
+Node: Pattern Overview408086
+Node: Regexp Patterns409763
+Node: Expression Patterns410305
+Node: Ranges414086
+Node: BEGIN/END417194
+Node: Using BEGIN/END417955
+Ref: Using BEGIN/END-Footnote-1420691
+Node: I/O And BEGIN/END420797
+Node: BEGINFILE/ENDFILE423111
+Node: Empty426024
+Node: Using Shell Variables426341
+Node: Action Overview428615
+Node: Statements430940
+Node: If Statement432788
+Node: While Statement434283
+Node: Do Statement436311
+Node: For Statement437459
+Node: Switch Statement440630
+Node: Break Statement443016
+Node: Continue Statement445108
+Node: Next Statement446935
+Node: Nextfile Statement449318
+Node: Exit Statement451970
+Node: Built-in Variables454373
+Node: User-modified455506
+Node: Auto-set463273
+Ref: Auto-set-Footnote-1479575
+Ref: Auto-set-Footnote-2479781
+Node: ARGC and ARGV479837
+Node: Pattern Action Summary484050
+Node: Arrays486480
+Node: Array Basics487809
+Node: Array Intro488653
+Ref: figure-array-elements490628
+Ref: Array Intro-Footnote-1493332
+Node: Reference to Elements493460
+Node: Assigning Elements495924
+Node: Array Example496415
+Node: Scanning an Array498174
+Node: Controlling Scanning501196
+Ref: Controlling Scanning-Footnote-1506595
+Node: Numeric Array Subscripts506911
+Node: Uninitialized Subscripts509095
+Node: Delete510714
+Ref: Delete-Footnote-1513466
+Node: Multidimensional513523
+Node: Multiscanning516618
+Node: Arrays of Arrays518209
+Node: Arrays Summary522976
+Node: Functions525069
+Node: Built-in526107
+Node: Calling Built-in527188
+Node: Numeric Functions529184
+Ref: Numeric Functions-Footnote-1533212
+Ref: Numeric Functions-Footnote-2533569
+Ref: Numeric Functions-Footnote-3533617
+Node: String Functions533889
+Ref: String Functions-Footnote-1557598
+Ref: String Functions-Footnote-2557726
+Ref: String Functions-Footnote-3557974
+Node: Gory Details558061
+Ref: table-sub-escapes559852
+Ref: table-sub-proposed561371
+Ref: table-posix-sub562734
+Ref: table-gensub-escapes564275
+Ref: Gory Details-Footnote-1565098
+Node: I/O Functions565252
+Ref: table-system-return-values571720
+Ref: I/O Functions-Footnote-1573700
+Ref: I/O Functions-Footnote-2573848
+Node: Time Functions573968
+Ref: Time Functions-Footnote-1584639
+Ref: Time Functions-Footnote-2584707
+Ref: Time Functions-Footnote-3584865
+Ref: Time Functions-Footnote-4584976
+Ref: Time Functions-Footnote-5585088
+Ref: Time Functions-Footnote-6585315
+Node: Bitwise Functions585581
+Ref: table-bitwise-ops586175
+Ref: Bitwise Functions-Footnote-1592238
+Ref: Bitwise Functions-Footnote-2592411
+Node: Type Functions592602
+Node: I18N Functions595353
+Node: User-defined597004
+Node: Definition Syntax597809
+Ref: Definition Syntax-Footnote-1603496
+Node: Function Example603567
+Ref: Function Example-Footnote-1606489
+Node: Function Caveats606511
+Node: Calling A Function607029
+Node: Variable Scope607987
+Node: Pass By Value/Reference610981
+Node: Return Statement614480
+Node: Dynamic Typing617459
+Node: Indirect Calls618389
+Ref: Indirect Calls-Footnote-1628641
+Node: Functions Summary628769
+Node: Library Functions631474
+Ref: Library Functions-Footnote-1635081
+Ref: Library Functions-Footnote-2635224
+Node: Library Names635395
+Ref: Library Names-Footnote-1638855
+Ref: Library Names-Footnote-2639078
+Node: General Functions639164
+Node: Strtonum Function640267
+Node: Assert Function643289
+Node: Round Function646615
+Node: Cliff Random Function648155
+Node: Ordinal Functions649171
+Ref: Ordinal Functions-Footnote-1652234
+Ref: Ordinal Functions-Footnote-2652486
+Node: Join Function652696
+Ref: Join Function-Footnote-1654466
+Node: Getlocaltime Function654666
+Node: Readfile Function658408
+Node: Shell Quoting660385
+Node: Data File Management661786
+Node: Filetrans Function662418
+Node: Rewind Function666514
+Node: File Checking668424
+Ref: File Checking-Footnote-1669758
+Node: Empty Files669959
+Node: Ignoring Assigns671938
+Node: Getopt Function673488
+Ref: Getopt Function-Footnote-1684957
+Node: Passwd Functions685157
+Ref: Passwd Functions-Footnote-1693996
+Node: Group Functions694084
+Ref: Group Functions-Footnote-1701982
+Node: Walking Arrays702189
+Node: Library Functions Summary705197
+Node: Library Exercises706603
+Node: Sample Programs707068
+Node: Running Examples707838
+Node: Clones708566
+Node: Cut Program709790
+Node: Egrep Program719719
+Ref: Egrep Program-Footnote-1727231
+Node: Id Program727341
+Node: Split Program731021
+Ref: Split Program-Footnote-1734479
+Node: Tee Program734608
+Node: Uniq Program737398
+Node: Wc Program744824
+Ref: Wc Program-Footnote-1749079
+Node: Miscellaneous Programs749173
+Node: Dupword Program750386
+Node: Alarm Program752416
+Node: Translate Program757271
+Ref: Translate Program-Footnote-1761836
+Node: Labels Program762106
+Ref: Labels Program-Footnote-1765457
+Node: Word Sorting765541
+Node: History Sorting769613
+Node: Extract Program771448
+Node: Simple Sed779502
+Node: Igawk Program782576
+Ref: Igawk Program-Footnote-1796907
+Ref: Igawk Program-Footnote-2797109
+Ref: Igawk Program-Footnote-3797231
+Node: Anagram Program797346
+Node: Signature Program800408
+Node: Programs Summary801655
+Node: Programs Exercises802869
+Ref: Programs Exercises-Footnote-1806998
+Node: Advanced Features807089
+Node: Nondecimal Data809079
+Node: Array Sorting810670
+Node: Controlling Array Traversal811370
+Ref: Controlling Array Traversal-Footnote-1819738
+Node: Array Sorting Functions819856
+Ref: Array Sorting Functions-Footnote-1824947
+Node: Two-way I/O825143
+Ref: Two-way I/O-Footnote-1831695
+Ref: Two-way I/O-Footnote-2831882
+Node: TCP/IP Networking831964
+Node: Profiling835082
+Ref: Profiling-Footnote-1843754
+Node: Advanced Features Summary844077
+Node: Internationalization845921
+Node: I18N and L10N847401
+Node: Explaining gettext848088
+Ref: Explaining gettext-Footnote-1853980
+Ref: Explaining gettext-Footnote-2854165
+Node: Programmer i18n854330
+Ref: Programmer i18n-Footnote-1859279
+Node: Translator i18n859328
+Node: String Extraction860122
+Ref: String Extraction-Footnote-1861254
+Node: Printf Ordering861340
+Ref: Printf Ordering-Footnote-1864126
+Node: I18N Portability864190
+Ref: I18N Portability-Footnote-1866646
+Node: I18N Example866709
+Ref: I18N Example-Footnote-1869515
+Node: Gawk I18N869588
+Node: I18N Summary870233
+Node: Debugger871574
+Node: Debugging872597
+Node: Debugging Concepts873038
+Node: Debugging Terms874847
+Node: Awk Debugging877422
+Node: Sample Debugging Session878328
+Node: Debugger Invocation878862
+Node: Finding The Bug880248
+Node: List of Debugger Commands886726
+Node: Breakpoint Control888059
+Node: Debugger Execution Control891753
+Node: Viewing And Changing Data895115
+Node: Execution Stack898489
+Node: Debugger Info900126
+Node: Miscellaneous Debugger Commands904197
+Node: Readline Support909259
+Node: Limitations910155
+Node: Debugging Summary912264
+Node: Arbitrary Precision Arithmetic913543
+Node: Computer Arithmetic915028
+Ref: table-numeric-ranges918794
+Ref: table-floating-point-ranges919287
+Ref: Computer Arithmetic-Footnote-1919945
+Node: Math Definitions920002
+Ref: table-ieee-formats923318
+Ref: Math Definitions-Footnote-1923921
+Node: MPFR features924026
+Node: FP Math Caution925744
+Ref: FP Math Caution-Footnote-1926816
+Node: Inexactness of computations927185
+Node: Inexact representation928145
+Node: Comparing FP Values929505
+Node: Errors accumulate930587
+Node: Getting Accuracy932020
+Node: Try To Round934730
+Node: Setting precision935629
+Ref: table-predefined-precision-strings936326
+Node: Setting the rounding mode938156
+Ref: table-gawk-rounding-modes938530
+Ref: Setting the rounding mode-Footnote-1942461
+Node: Arbitrary Precision Integers942640
+Ref: Arbitrary Precision Integers-Footnote-1945815
+Node: Checking for MPFR945964
+Node: POSIX Floating Point Problems947438
+Ref: POSIX Floating Point Problems-Footnote-1951309
+Node: Floating point summary951347
+Node: Dynamic Extensions953537
+Node: Extension Intro955090
+Node: Plugin License956356
+Node: Extension Mechanism Outline957153
+Ref: figure-load-extension957592
+Ref: figure-register-new-function959157
+Ref: figure-call-new-function960249
+Node: Extension API Description962311
+Node: Extension API Functions Introduction963953
+Node: General Data Types969493
+Ref: General Data Types-Footnote-1977854
+Node: Memory Allocation Functions978153
+Ref: Memory Allocation Functions-Footnote-1982363
+Node: Constructor Functions982462
+Node: Registration Functions986048
+Node: Extension Functions986733
+Node: Exit Callback Functions991948
+Node: Extension Version String993198
+Node: Input Parsers993861
+Node: Output Wrappers1006582
+Node: Two-way processors1011094
+Node: Printing Messages1013359
+Ref: Printing Messages-Footnote-11014530
+Node: Updating ERRNO1014683
+Node: Requesting Values1015422
+Ref: table-value-types-returned1016159
+Node: Accessing Parameters1017095
+Node: Symbol Table Access1018330
+Node: Symbol table by name1018842
+Node: Symbol table by cookie1020631
+Ref: Symbol table by cookie-Footnote-11024816
+Node: Cached values1024880
+Ref: Cached values-Footnote-11028416
+Node: Array Manipulation1028569
+Ref: Array Manipulation-Footnote-11029660
+Node: Array Data Types1029697
+Ref: Array Data Types-Footnote-11032355
+Node: Array Functions1032447
+Node: Flattening Arrays1036945
+Node: Creating Arrays1043921
+Node: Redirection API1048688
+Node: Extension API Variables1051521
+Node: Extension Versioning1052232
+Ref: gawk-api-version1052661
+Node: Extension GMP/MPFR Versioning1054392
+Node: Extension API Informational Variables1056020
+Node: Extension API Boilerplate1057093
+Node: Changes from API V11061067
+Node: Finding Extensions1062639
+Node: Extension Example1063198
+Node: Internal File Description1063996
+Node: Internal File Ops1068076
+Ref: Internal File Ops-Footnote-11079426
+Node: Using Internal File Ops1079566
+Ref: Using Internal File Ops-Footnote-11081949
+Node: Extension Samples1082223
+Node: Extension Sample File Functions1083752
+Node: Extension Sample Fnmatch1091401
+Node: Extension Sample Fork1092888
+Node: Extension Sample Inplace1094106
+Node: Extension Sample Ord1097323
+Node: Extension Sample Readdir1098159
+Ref: table-readdir-file-types1099048
+Node: Extension Sample Revout1099853
+Node: Extension Sample Rev2way1100442
+Node: Extension Sample Read write array1101182
+Node: Extension Sample Readfile1103124
+Node: Extension Sample Time1104219
+Node: Extension Sample API Tests1105567
+Node: gawkextlib1106059
+Node: Extension summary1108977
+Node: Extension Exercises1112679
+Node: Language History1114177
+Node: V7/SVR3.11115833
+Node: SVR41117985
+Node: POSIX1119419
+Node: BTL1120799
+Node: POSIX/GNU1121528
+Node: Feature History1127306
+Node: Common Extensions1143165
+Node: Ranges and Locales1144448
+Ref: Ranges and Locales-Footnote-11149064
+Ref: Ranges and Locales-Footnote-21149091
+Ref: Ranges and Locales-Footnote-31149326
+Node: Contributors1149547
+Node: History summary1155492
+Node: Installation1156872
+Node: Gawk Distribution1157816
+Node: Getting1158300
+Node: Extracting1159263
+Node: Distribution contents1160901
+Node: Unix Installation1167381
+Node: Quick Installation1168063
+Node: Shell Startup Files1170477
+Node: Additional Configuration Options1171566
+Node: Configuration Philosophy1173859
+Node: Non-Unix Installation1176228
+Node: PC Installation1176688
+Node: PC Binary Installation1177526
+Node: PC Compiling1177961
+Node: PC Using1179078
+Node: Cygwin1182293
+Node: MSYS1183392
+Node: VMS Installation1183893
+Node: VMS Compilation1184684
+Ref: VMS Compilation-Footnote-11185913
+Node: VMS Dynamic Extensions1185971
+Node: VMS Installation Details1187656
+Node: VMS Running1189909
+Node: VMS GNV1194188
+Node: VMS Old Gawk1194923
+Node: Bugs1195394
+Node: Bug address1196057
+Node: Usenet1198849
+Node: Maintainers1199626
+Node: Other Versions1200887
+Node: Installation summary1207649
+Node: Notes1208851
+Node: Compatibility Mode1209716
+Node: Additions1210498
+Node: Accessing The Source1211423
+Node: Adding Code1212860
+Node: New Ports1219079
+Node: Derived Files1223567
+Ref: Derived Files-Footnote-11229213
+Ref: Derived Files-Footnote-21229248
+Ref: Derived Files-Footnote-31229846
+Node: Future Extensions1229960
+Node: Implementation Limitations1230618
+Node: Extension Design1231801
+Node: Old Extension Problems1232955
+Ref: Old Extension Problems-Footnote-11234473
+Node: Extension New Mechanism Goals1234530
+Ref: Extension New Mechanism Goals-Footnote-11237894
+Node: Extension Other Design Decisions1238083
+Node: Extension Future Growth1240196
+Node: Old Extension Mechanism1241032
+Node: Notes summary1242795
+Node: Basic Concepts1243977
+Node: Basic High Level1244658
+Ref: figure-general-flow1244940
+Ref: figure-process-flow1245625
+Ref: Basic High Level-Footnote-11248926
+Node: Basic Data Typing1249111
+Node: Glossary1252439
+Node: Copying1284277
+Node: GNU Free Documentation License1321820
+Node: Index1346940
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 54b21680..7da5048c 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -6461,6 +6461,12 @@ Another predefined variable, @code{NR}, records the total number of input
 records read so far from all @value{DF}s.  It starts at zero, but is
 never automatically reset to zero.
 
+Normally, records are separated by newline characters.  You can control how
+records are separated by assigning values to the built-in variable @code{RS}.
+If @code{RS} is any single character, that character separates records.
+Otherwise (in @command{gawk}), @code{RS} is treated as a regular expression.
+This mechanism is explained in greater detail shortly.
+
 @menu
 * awk split records::           How standard @command{awk} splits records.
 * gawk split records::          How @command{gawk} splits records.
@@ -6647,9 +6653,9 @@ sets the variable @code{RT} to the text in the input that matched
 
 @cindex common extensions, @code{RS} as a regexp
 @cindex extensions, common@comma{} @code{RS} as a regexp
-When using @command{gawk},
-the value of @code{RS} is not limited to a one-character
-string.  It can be any regular expression
+When using @command{gawk}, the value of @code{RS} is not limited to a
+one-character string.  If it contains more than one character, it is
+treated as a regular expression
 (@pxref{Regexp}). @value{COMMONEXT}
 In general, each record
 ends at the next string that matches the regular expression; the next
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 8ed19cbf..a9a670db 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -6244,6 +6244,12 @@ Another predefined variable, @code{NR}, records the total number of input
 records read so far from all @value{DF}s.  It starts at zero, but is
 never automatically reset to zero.
 
+Normally, records are separated by newline characters.  You can control how
+records are separated by assigning values to the built-in variable @code{RS}.
+If @code{RS} is any single character, that character separates records.
+Otherwise (in @command{gawk}), @code{RS} is treated as a regular expression.
+This mechanism is explained in greater detail shortly.
+
 @menu
 * awk split records::           How standard @command{awk} splits records.
 * gawk split records::          How @command{gawk} splits records.
@@ -6430,9 +6436,9 @@ sets the variable @code{RT} to the text in the input that matched
 
 @cindex common extensions, @code{RS} as a regexp
 @cindex extensions, common@comma{} @code{RS} as a regexp
-When using @command{gawk},
-the value of @code{RS} is not limited to a one-character
-string.  It can be any regular expression
+When using @command{gawk}, the value of @code{RS} is not limited to a
+one-character string.  If it contains more than one character, it is
+treated as a regular expression
 (@pxref{Regexp}). @value{COMMONEXT}
 In general, each record
 ends at the next string that matches the regular expression; the next