Improve material on function caveats.

4 files changed, 723 insertions, 618 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 71b99f17..bc0d9beb 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -2,6 +2,8 @@
 
 	* gawktexi.in: Don't use `\global\usebracesinindexestrue' as it's
 	no longer supported.
+	(Function Calling): Renamed from `Function Caveats'.
+	(Function Caveats): New node.
 
 2019-02-07         Arnold D. Robbins     <arnold@skeeve.com>
 
diff --git a/doc/gawk.info b/doc/gawk.info
index d1fe12ab..891685aa 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -400,10 +400,11 @@ in (a) below.  A copy of the license is included in the section entitled
                                         mean.
 * Function Example::                    An example function definition and
                                         what it does.
-* Function Caveats::                    Things to watch out for.
+* Function Calling::                    Calling user-defined functions.
 * Calling A Function::                  Don't use spaces.
 * Variable Scope::                      Controlling variable scope.
 * Pass By Value/Reference::             Passing parameters.
+* Function Caveats::                    Other points to know about functions.
 * Return Statement::                    Specifying the value a function
                                         returns.
 * Dynamic Typing::                      How variable types can change at
@@ -14238,7 +14239,7 @@ tell 'awk' what they should do).
 * Definition Syntax::           How to write definitions and what they mean.
 * Function Example::            An example function definition and what it
                                 does.
-* Function Caveats::            Things to watch out for.
+* Function Calling::            Calling user-defined functions.
 * Return Statement::            Specifying the value a function returns.
 * Dynamic Typing::              How variable types can change at runtime.
 
@@ -14364,7 +14365,7 @@ keyword 'function' when defining a function.
    (1) This program won't actually run, because 'foo()' is undefined.
 
 
-File: gawk.info,  Node: Function Example,  Next: Function Caveats,  Prev: Definition Syntax,  Up: User-defined
+File: gawk.info,  Node: Function Example,  Next: Function Calling,  Prev: Definition Syntax,  Up: User-defined
 
 9.2.2 Function Definition Examples
 ----------------------------------
@@ -14460,7 +14461,7 @@ user-level code could have changed 'PROCINFO["strftime"]'.
    (1) Late in 2012.
 
 
-File: gawk.info,  Node: Function Caveats,  Next: Return Statement,  Prev: Function Example,  Up: User-defined
+File: gawk.info,  Node: Function Calling,  Next: Return Statement,  Prev: Function Example,  Up: User-defined
 
 9.2.3 Calling User-Defined Functions
 ------------------------------------
@@ -14474,9 +14475,10 @@ the function.
 * Calling A Function::          Don't use spaces.
 * Variable Scope::              Controlling variable scope.
 * Pass By Value/Reference::     Passing parameters.
+* Function Caveats::            Other points to know about functions.
 
 
-File: gawk.info,  Node: Calling A Function,  Next: Variable Scope,  Up: Function Caveats
+File: gawk.info,  Node: Calling A Function,  Next: Variable Scope,  Up: Function Calling
 
 9.2.3.1 Writing a Function Call
 ...............................
@@ -14498,7 +14500,7 @@ concatenation):
      not a variable name, and reports an error.
 
 
-File: gawk.info,  Node: Variable Scope,  Next: Pass By Value/Reference,  Prev: Calling A Function,  Up: Function Caveats
+File: gawk.info,  Node: Variable Scope,  Next: Pass By Value/Reference,  Prev: Calling A Function,  Up: Function Calling
 
 9.2.3.2 Controlling Variable Scope
 ..................................
@@ -14618,7 +14620,7 @@ create new arrays.  Consider this example:
      At level 2, index 2 is found in a
 
 
-File: gawk.info,  Node: Pass By Value/Reference,  Prev: Variable Scope,  Up: Function Caveats
+File: gawk.info,  Node: Pass By Value/Reference,  Next: Function Caveats,  Prev: Variable Scope,  Up: Function Calling
 
 9.2.3.3 Passing Function Arguments by Value Or by Reference
 ...........................................................
@@ -14685,7 +14687,13 @@ function _are_ visible outside that function.
      prints 'a[1] = 1, a[2] = two, a[3] = 3', because 'changeit()'
      stores '"two"' in the second element of 'a'.
 
-   Some 'awk' implementations allow you to call a function that has not
+
+File: gawk.info,  Node: Function Caveats,  Prev: Pass By Value/Reference,  Up: Function Calling
+
+9.2.3.4 Other Points About Calling Functions
+............................................
+
+Some 'awk' implementations allow you to call a function that has not
 been defined.  They only report a problem at runtime, when the program
 actually tries to call the function.  For example:
 
@@ -14710,8 +14718,39 @@ the 'next' statement or the 'nextfile' statement (*note Next
 Statement::, and *note Nextfile Statement::) inside a user-defined
 function.  'gawk' does not have this limitation.
 
+   You can call a function and pass it more parameters than it was
+declared with, like so:
+
+     function foo(p1, p2)
+     {
+         ...
+     }
+
+     BEGIN {
+         foo(1, 2, 3, 4)
+     }
+
+   Doing so is bad practice, however.  The called function cannot do
+anything with the additional values being passed to it, so 'awk'
+evaluates the expressions but then just throws them away.
+
+   More importantly, such a call is confusing for whoever will next read
+your program.(1)  Function parameters generally are input items that
+influence the computation performed by the function.  Calling a function
+with more paramaters than it accepts gives the false impression that
+those values are important to the function, when in fact they are not.
+
+   Because this is such a bad practice, 'gawk' _unconditionally_ issues
+a warning whenever it executes such a function call.  (If you don't like
+the warning, fix your code!  It's incorrect, after all.)
+
+   ---------- Footnotes ----------
+
+   (1) Said person might even be you, sometime in the future, at which
+point you will wonder, "what was I thinking?!?"
+
 
-File: gawk.info,  Node: Return Statement,  Next: Dynamic Typing,  Prev: Function Caveats,  Up: User-defined
+File: gawk.info,  Node: Return Statement,  Next: Dynamic Typing,  Prev: Function Calling,  Up: User-defined
 
 9.2.4 The 'return' Statement
 ----------------------------
@@ -35129,10 +35168,9 @@ Index
 * functions, names of:                   Definition Syntax.   (line  24)
 * functions, recursive:                  Definition Syntax.   (line  89)
 * functions, string-translation:         I18N Functions.      (line   6)
-* functions, undefined:                  Pass By Value/Reference.
-                                                              (line  68)
+* functions, undefined:                  Function Caveats.    (line   6)
 * functions, user-defined:               User-defined.        (line   6)
-* functions, user-defined, calling:      Function Caveats.    (line   6)
+* functions, user-defined, calling:      Function Calling.    (line   6)
 * functions, user-defined, counts, in a profile: Profiling.   (line 137)
 * functions, user-defined, library of:   Library Functions.   (line   6)
 * functions, user-defined, next/nextfile statements and: Next Statement.
@@ -35565,8 +35603,7 @@ Index
 * lint checking, issuing warnings:       Options.             (line 210)
 * lint checking, POSIXLY_CORRECT environment variable: Options.
                                                               (line 368)
-* lint checking, undefined functions:    Pass By Value/Reference.
-                                                              (line  85)
+* lint checking, undefined functions:    Function Caveats.    (line  23)
 * LINT variable:                         User-modified.       (line  90)
 * Linux:                                 Manual History.      (line  28)
 * Linux <1>:                             I18N Example.        (line  57)
@@ -35918,8 +35955,8 @@ Index
 * portability, internationalization and: I18N Portability.    (line   6)
 * portability, length() function:        String Functions.    (line 180)
 * portability, new awk vs. old awk:      Strings And Numbers. (line  56)
-* portability, next statement in user-defined functions: Pass By Value/Reference.
-                                                              (line  88)
+* portability, next statement in user-defined functions: Function Caveats.
+                                                              (line  26)
 * portability, NF variable, decrementing: Changing Fields.    (line 115)
 * portability, operators:                Increment Ops.       (line  60)
 * portability, operators, not in POSIX awk: Precedence.       (line  97)
@@ -36631,8 +36668,7 @@ Index
                                                               (line  82)
 * unassigned array elements:             Reference to Elements.
                                                               (line  18)
-* undefined functions:                   Pass By Value/Reference.
-                                                              (line  68)
+* undefined functions:                   Function Caveats.    (line   6)
 * underscore (_), C macro:               Explaining gettext.  (line  71)
 * underscore (_), in names of private variables: Library Names.
                                                               (line  29)
@@ -36775,594 +36811,596 @@ Index
 
 Tag Table:
 Node: Top1200
-Node: Foreword344048
-Node: Foreword448490
-Node: Preface50022
-Ref: Preface-Footnote-152881
-Ref: Preface-Footnote-252988
-Ref: Preface-Footnote-353222
-Node: History53364
-Node: Names55716
-Ref: Names-Footnote-156810
-Node: This Manual56957
-Ref: This Manual-Footnote-163596
-Node: Conventions63696
-Node: Manual History66051
-Ref: Manual History-Footnote-169048
-Ref: Manual History-Footnote-269089
-Node: How To Contribute69163
-Node: Acknowledgments70089
-Node: Getting Started74997
-Node: Running gawk77436
-Node: One-shot78626
-Node: Read Terminal79889
-Node: Long81882
-Node: Executable Scripts83395
-Ref: Executable Scripts-Footnote-186190
-Node: Comments86293
-Node: Quoting88777
-Node: DOS Quoting94294
-Node: Sample Data Files96350
-Node: Very Simple98945
-Node: Two Rules103847
-Node: More Complex105732
-Node: Statements/Lines108598
-Ref: Statements/Lines-Footnote-1113057
-Node: Other Features113322
-Node: When114258
-Ref: When-Footnote-1116012
-Node: Intro Summary116077
-Node: Invoking Gawk116961
-Node: Command Line118475
-Node: Options119273
-Ref: Options-Footnote-1136351
-Ref: Options-Footnote-2136582
-Node: Other Arguments136607
-Node: Naming Standard Input139554
-Node: Environment Variables140764
-Node: AWKPATH Variable141322
-Ref: AWKPATH Variable-Footnote-1144734
-Ref: AWKPATH Variable-Footnote-2144768
-Node: AWKLIBPATH Variable145029
-Node: Other Environment Variables146687
-Node: Exit Status150508
-Node: Include Files151185
-Node: Loading Shared Libraries154875
-Node: Obsolete156303
-Node: Undocumented156995
-Node: Invoking Summary157292
-Node: Regexp158952
-Node: Regexp Usage160406
-Node: Escape Sequences162443
-Node: Regexp Operators168675
-Ref: Regexp Operators-Footnote-1176091
-Ref: Regexp Operators-Footnote-2176238
-Node: Bracket Expressions176336
-Ref: table-char-classes178812
-Node: Leftmost Longest182138
-Node: Computed Regexps183441
-Node: GNU Regexp Operators186868
-Node: Case-sensitivity190547
-Ref: Case-sensitivity-Footnote-1193434
-Ref: Case-sensitivity-Footnote-2193669
-Node: Regexp Summary193777
-Node: Reading Files195243
-Node: Records197512
-Node: awk split records198587
-Node: gawk split records203862
-Ref: gawk split records-Footnote-1208448
-Node: Fields208485
-Node: Nonconstant Fields211226
-Ref: Nonconstant Fields-Footnote-1213462
-Node: Changing Fields213666
-Node: Field Separators219697
-Node: Default Field Splitting222395
-Node: Regexp Field Splitting223513
-Node: Single Character Fields226866
-Node: Command Line Field Separator227926
-Node: Full Line Fields231144
-Ref: Full Line Fields-Footnote-1232666
-Ref: Full Line Fields-Footnote-2232712
-Node: Field Splitting Summary232813
-Node: Constant Size234887
-Node: Fixed width data235619
-Node: Skipping intervening239086
-Node: Allowing trailing data239884
-Node: Fields with fixed data240921
-Node: Splitting By Content242439
-Ref: Splitting By Content-Footnote-1246089
-Node: Testing field creation246252
-Node: Multiple Line247877
-Ref: Multiple Line-Footnote-1253761
-Node: Getline253940
-Node: Plain Getline256409
-Node: Getline/Variable259050
-Node: Getline/File260201
-Node: Getline/Variable/File261589
-Ref: Getline/Variable/File-Footnote-1263194
-Node: Getline/Pipe263282
-Node: Getline/Variable/Pipe265989
-Node: Getline/Coprocess267124
-Node: Getline/Variable/Coprocess268391
-Node: Getline Notes269133
-Node: Getline Summary271930
-Ref: table-getline-variants272354
-Node: Read Timeout273102
-Ref: Read Timeout-Footnote-1277008
-Node: Retrying Input277066
-Node: Command-line directories278265
-Node: Input Summary279171
-Node: Input Exercises282343
-Node: Printing283071
-Node: Print284905
-Node: Print Examples286362
-Node: Output Separators289142
-Node: OFMT291159
-Node: Printf292515
-Node: Basic Printf293300
-Node: Control Letters294874
-Node: Format Modifiers300036
-Node: Printf Examples306051
-Node: Redirection308537
-Node: Special FD315378
-Ref: Special FD-Footnote-1318546
-Node: Special Files318620
-Node: Other Inherited Files319237
-Node: Special Network320238
-Node: Special Caveats321098
-Node: Close Files And Pipes322047
-Ref: table-close-pipe-return-values328954
-Ref: Close Files And Pipes-Footnote-1329767
-Ref: Close Files And Pipes-Footnote-2329915
-Node: Nonfatal330067
-Node: Output Summary332405
-Node: Output Exercises333627
-Node: Expressions334306
-Node: Values335494
-Node: Constants336172
-Node: Scalar Constants336863
-Ref: Scalar Constants-Footnote-1339387
-Node: Nondecimal-numbers339637
-Node: Regexp Constants342638
-Node: Using Constant Regexps343164
-Node: Standard Regexp Constants343786
-Node: Strong Regexp Constants346974
-Node: Variables349932
-Node: Using Variables350589
-Node: Assignment Options352499
-Node: Conversion354966
-Node: Strings And Numbers355490
-Ref: Strings And Numbers-Footnote-1358553
-Node: Locale influences conversions358662
-Ref: table-locale-affects361420
-Node: All Operators362038
-Node: Arithmetic Ops362667
-Node: Concatenation365173
-Ref: Concatenation-Footnote-1368020
-Node: Assignment Ops368127
-Ref: table-assign-ops373118
-Node: Increment Ops374431
-Node: Truth Values and Conditions377891
-Node: Truth Values378965
-Node: Typing and Comparison380013
-Node: Variable Typing380833
-Ref: Variable Typing-Footnote-1387296
-Ref: Variable Typing-Footnote-2387368
-Node: Comparison Operators387445
-Ref: table-relational-ops387864
-Node: POSIX String Comparison391359
-Ref: POSIX String Comparison-Footnote-1393054
-Ref: POSIX String Comparison-Footnote-2393193
-Node: Boolean Ops393277
-Ref: Boolean Ops-Footnote-1397759
-Node: Conditional Exp397851
-Node: Function Calls399587
-Node: Precedence403464
-Node: Locales407123
-Node: Expressions Summary408755
-Node: Patterns and Actions411328
-Node: Pattern Overview412448
-Node: Regexp Patterns414125
-Node: Expression Patterns414667
-Node: Ranges418448
-Node: BEGIN/END421556
-Node: Using BEGIN/END422317
-Ref: Using BEGIN/END-Footnote-1425053
-Node: I/O And BEGIN/END425159
-Node: BEGINFILE/ENDFILE427473
-Node: Empty430386
-Node: Using Shell Variables430703
-Node: Action Overview432977
-Node: Statements435302
-Node: If Statement437150
-Node: While Statement438645
-Node: Do Statement440673
-Node: For Statement441821
-Node: Switch Statement444992
-Node: Break Statement447378
-Node: Continue Statement449470
-Node: Next Statement451297
-Node: Nextfile Statement453680
-Node: Exit Statement456332
-Node: Built-in Variables458735
-Node: User-modified459868
-Node: Auto-set467635
-Ref: Auto-set-Footnote-1484442
-Ref: Auto-set-Footnote-2484648
-Node: ARGC and ARGV484704
-Node: Pattern Action Summary488917
-Node: Arrays491347
-Node: Array Basics492676
-Node: Array Intro493520
-Ref: figure-array-elements495495
-Ref: Array Intro-Footnote-1498199
-Node: Reference to Elements498327
-Node: Assigning Elements500791
-Node: Array Example501282
-Node: Scanning an Array503041
-Node: Controlling Scanning506063
-Ref: Controlling Scanning-Footnote-1511462
-Node: Numeric Array Subscripts511778
-Node: Uninitialized Subscripts513962
-Node: Delete515581
-Ref: Delete-Footnote-1518333
-Node: Multidimensional518390
-Node: Multiscanning521485
-Node: Arrays of Arrays523076
-Node: Arrays Summary527844
-Node: Functions529937
-Node: Built-in530975
-Node: Calling Built-in532056
-Node: Numeric Functions534052
-Ref: Numeric Functions-Footnote-1538080
-Ref: Numeric Functions-Footnote-2538725
-Ref: Numeric Functions-Footnote-3538773
-Node: String Functions539045
-Ref: String Functions-Footnote-1562903
-Ref: String Functions-Footnote-2563031
-Ref: String Functions-Footnote-3563279
-Node: Gory Details563366
-Ref: table-sub-escapes565157
-Ref: table-sub-proposed566676
-Ref: table-posix-sub568039
-Ref: table-gensub-escapes569580
-Ref: Gory Details-Footnote-1570403
-Node: I/O Functions570557
-Ref: table-system-return-values577025
-Ref: I/O Functions-Footnote-1579105
-Ref: I/O Functions-Footnote-2579253
-Node: Time Functions579373
-Ref: Time Functions-Footnote-1590044
-Ref: Time Functions-Footnote-2590112
-Ref: Time Functions-Footnote-3590270
-Ref: Time Functions-Footnote-4590381
-Ref: Time Functions-Footnote-5590493
-Ref: Time Functions-Footnote-6590720
-Node: Bitwise Functions590986
-Ref: table-bitwise-ops591580
-Ref: Bitwise Functions-Footnote-1597643
-Ref: Bitwise Functions-Footnote-2597816
-Node: Type Functions598007
-Node: I18N Functions600758
-Node: User-defined602409
-Node: Definition Syntax603214
-Ref: Definition Syntax-Footnote-1608901
-Node: Function Example608972
-Ref: Function Example-Footnote-1611894
-Node: Function Caveats611916
-Node: Calling A Function612434
-Node: Variable Scope613392
-Node: Pass By Value/Reference616386
-Node: Return Statement619885
-Node: Dynamic Typing622864
-Node: Indirect Calls623794
-Ref: Indirect Calls-Footnote-1634046
-Node: Functions Summary634174
-Node: Library Functions636879
-Ref: Library Functions-Footnote-1640486
-Ref: Library Functions-Footnote-2640629
-Node: Library Names640800
-Ref: Library Names-Footnote-1644467
-Ref: Library Names-Footnote-2644690
-Node: General Functions644776
-Node: Strtonum Function645879
-Node: Assert Function648901
-Node: Round Function652227
-Node: Cliff Random Function653767
-Node: Ordinal Functions654783
-Ref: Ordinal Functions-Footnote-1657846
-Ref: Ordinal Functions-Footnote-2658098
-Node: Join Function658308
-Ref: Join Function-Footnote-1660078
-Node: Getlocaltime Function660278
-Node: Readfile Function664020
-Node: Shell Quoting665997
-Node: Data File Management667398
-Node: Filetrans Function668030
-Node: Rewind Function672126
-Node: File Checking674035
-Ref: File Checking-Footnote-1675369
-Node: Empty Files675570
-Node: Ignoring Assigns677549
-Node: Getopt Function679099
-Ref: Getopt Function-Footnote-1690568
-Node: Passwd Functions690768
-Ref: Passwd Functions-Footnote-1699607
-Node: Group Functions699695
-Ref: Group Functions-Footnote-1707593
-Node: Walking Arrays707800
-Node: Library Functions Summary710808
-Node: Library Exercises712214
-Node: Sample Programs712679
-Node: Running Examples713449
-Node: Clones714177
-Node: Cut Program715401
-Node: Egrep Program725330
-Ref: Egrep Program-Footnote-1732842
-Node: Id Program732952
-Node: Split Program736632
-Ref: Split Program-Footnote-1740090
-Node: Tee Program740219
-Node: Uniq Program743009
-Node: Wc Program750630
-Ref: Wc Program-Footnote-1754885
-Node: Miscellaneous Programs754979
-Node: Dupword Program756192
-Node: Alarm Program758222
-Node: Translate Program763077
-Ref: Translate Program-Footnote-1767642
-Node: Labels Program767912
-Ref: Labels Program-Footnote-1771263
-Node: Word Sorting771347
-Node: History Sorting775419
-Node: Extract Program777254
-Node: Simple Sed785308
-Node: Igawk Program788382
-Ref: Igawk Program-Footnote-1802713
-Ref: Igawk Program-Footnote-2802915
-Ref: Igawk Program-Footnote-3803037
-Node: Anagram Program803152
-Node: Signature Program806214
-Node: Programs Summary807461
-Node: Programs Exercises808675
-Ref: Programs Exercises-Footnote-1812804
-Node: Advanced Features812895
-Node: Nondecimal Data814885
-Node: Array Sorting816476
-Node: Controlling Array Traversal817176
-Ref: Controlling Array Traversal-Footnote-1825544
-Node: Array Sorting Functions825662
-Ref: Array Sorting Functions-Footnote-1830753
-Node: Two-way I/O830949
-Ref: Two-way I/O-Footnote-1838670
-Ref: Two-way I/O-Footnote-2838857
-Node: TCP/IP Networking838939
-Node: Profiling842057
-Node: Advanced Features Summary851075
-Node: Internationalization852919
-Node: I18N and L10N854399
-Node: Explaining gettext855086
-Ref: Explaining gettext-Footnote-1860978
-Ref: Explaining gettext-Footnote-2861163
-Node: Programmer i18n861328
-Ref: Programmer i18n-Footnote-1866277
-Node: Translator i18n866326
-Node: String Extraction867120
-Ref: String Extraction-Footnote-1868252
-Node: Printf Ordering868338
-Ref: Printf Ordering-Footnote-1871124
-Node: I18N Portability871188
-Ref: I18N Portability-Footnote-1873644
-Node: I18N Example873707
-Ref: I18N Example-Footnote-1876982
-Ref: I18N Example-Footnote-2877055
-Node: Gawk I18N877164
-Node: I18N Summary877809
-Node: Debugger879150
-Node: Debugging880150
-Node: Debugging Concepts880591
-Node: Debugging Terms882400
-Node: Awk Debugging884975
-Ref: Awk Debugging-Footnote-1885920
-Node: Sample Debugging Session886052
-Node: Debugger Invocation886586
-Node: Finding The Bug887972
-Node: List of Debugger Commands894446
-Node: Breakpoint Control895779
-Node: Debugger Execution Control899473
-Node: Viewing And Changing Data902835
-Node: Execution Stack906209
-Node: Debugger Info907846
-Node: Miscellaneous Debugger Commands911917
-Node: Readline Support916979
-Node: Limitations917875
-Node: Debugging Summary919984
-Node: Namespaces921263
-Node: Global Namespace922342
-Node: Qualified Names923740
-Node: Default Namespace924739
-Node: Changing The Namespace925480
-Node: Naming Rules927094
-Node: Internal Name Management928942
-Node: Namespace Example929984
-Node: Namespace And Features932546
-Node: Namespace Summary933981
-Node: Arbitrary Precision Arithmetic935458
-Node: Computer Arithmetic936945
-Ref: table-numeric-ranges940711
-Ref: table-floating-point-ranges941204
-Ref: Computer Arithmetic-Footnote-1941862
-Node: Math Definitions941919
-Ref: table-ieee-formats945235
-Ref: Math Definitions-Footnote-1945838
-Node: MPFR features945943
-Node: FP Math Caution947661
-Ref: FP Math Caution-Footnote-1948733
-Node: Inexactness of computations949102
-Node: Inexact representation950062
-Node: Comparing FP Values951422
-Node: Errors accumulate952663
-Node: Getting Accuracy954096
-Node: Try To Round956806
-Node: Setting precision957705
-Ref: table-predefined-precision-strings958402
-Node: Setting the rounding mode960232
-Ref: table-gawk-rounding-modes960606
-Ref: Setting the rounding mode-Footnote-1964537
-Node: Arbitrary Precision Integers964716
-Ref: Arbitrary Precision Integers-Footnote-1967891
-Node: Checking for MPFR968040
-Node: POSIX Floating Point Problems969514
-Ref: POSIX Floating Point Problems-Footnote-1973799
-Node: Floating point summary973837
-Node: Dynamic Extensions976027
-Node: Extension Intro977580
-Node: Plugin License978846
-Node: Extension Mechanism Outline979643
-Ref: figure-load-extension980082
-Ref: figure-register-new-function981647
-Ref: figure-call-new-function982739
-Node: Extension API Description984801
-Node: Extension API Functions Introduction986443
-Ref: table-api-std-headers988279
-Node: General Data Types992144
-Ref: General Data Types-Footnote-11000505
-Node: Memory Allocation Functions1000804
-Ref: Memory Allocation Functions-Footnote-11005014
-Node: Constructor Functions1005113
-Node: Registration Functions1008699
-Node: Extension Functions1009384
-Node: Exit Callback Functions1014706
-Node: Extension Version String1015956
-Node: Input Parsers1016619
-Node: Output Wrappers1029340
-Node: Two-way processors1033852
-Node: Printing Messages1036117
-Ref: Printing Messages-Footnote-11037288
-Node: Updating ERRNO1037441
-Node: Requesting Values1038180
-Ref: table-value-types-returned1038917
-Node: Accessing Parameters1039853
-Node: Symbol Table Access1041088
-Node: Symbol table by name1041600
-Ref: Symbol table by name-Footnote-11044624
-Node: Symbol table by cookie1044752
-Ref: Symbol table by cookie-Footnote-11048937
-Node: Cached values1049001
-Ref: Cached values-Footnote-11052537
-Node: Array Manipulation1052690
-Ref: Array Manipulation-Footnote-11053781
-Node: Array Data Types1053818
-Ref: Array Data Types-Footnote-11056476
-Node: Array Functions1056568
-Node: Flattening Arrays1061066
-Node: Creating Arrays1068042
-Node: Redirection API1072809
-Node: Extension API Variables1075642
-Node: Extension Versioning1076353
-Ref: gawk-api-version1076782
-Node: Extension GMP/MPFR Versioning1078513
-Node: Extension API Informational Variables1080141
-Node: Extension API Boilerplate1081214
-Node: Changes from API V11085188
-Node: Finding Extensions1086760
-Node: Extension Example1087319
-Node: Internal File Description1088117
-Node: Internal File Ops1092197
-Ref: Internal File Ops-Footnote-11103547
-Node: Using Internal File Ops1103687
-Ref: Using Internal File Ops-Footnote-11106070
-Node: Extension Samples1106344
-Node: Extension Sample File Functions1107873
-Node: Extension Sample Fnmatch1115522
-Node: Extension Sample Fork1117009
-Node: Extension Sample Inplace1118227
-Node: Extension Sample Ord1121531
-Node: Extension Sample Readdir1122367
-Ref: table-readdir-file-types1123256
-Node: Extension Sample Revout1124061
-Node: Extension Sample Rev2way1124650
-Node: Extension Sample Read write array1125390
-Node: Extension Sample Readfile1127332
-Node: Extension Sample Time1128427
-Node: Extension Sample API Tests1129775
-Node: gawkextlib1130267
-Node: Extension summary1133185
-Node: Extension Exercises1136887
-Node: Language History1138129
-Node: V7/SVR3.11139785
-Node: SVR41141937
-Node: POSIX1143371
-Node: BTL1144751
-Node: POSIX/GNU1145480
-Node: Feature History1151258
-Node: Common Extensions1167304
-Node: Ranges and Locales1168587
-Ref: Ranges and Locales-Footnote-11173203
-Ref: Ranges and Locales-Footnote-21173230
-Ref: Ranges and Locales-Footnote-31173465
-Node: Contributors1173686
-Node: History summary1179631
-Node: Installation1181011
-Node: Gawk Distribution1181955
-Node: Getting1182439
-Node: Extracting1183402
-Node: Distribution contents1185040
-Node: Unix Installation1191520
-Node: Quick Installation1192202
-Node: Shell Startup Files1194616
-Node: Additional Configuration Options1195705
-Node: Configuration Philosophy1197870
-Node: Non-Unix Installation1200239
-Node: PC Installation1200699
-Node: PC Binary Installation1201537
-Node: PC Compiling1201972
-Node: PC Using1203089
-Node: Cygwin1206642
-Node: MSYS1207741
-Node: VMS Installation1208242
-Node: VMS Compilation1209033
-Ref: VMS Compilation-Footnote-11210262
-Node: VMS Dynamic Extensions1210320
-Node: VMS Installation Details1212005
-Node: VMS Running1214258
-Node: VMS GNV1218537
-Node: VMS Old Gawk1219272
-Node: Bugs1219743
-Node: Bug address1220406
-Node: Usenet1223388
-Node: Maintainers1224392
-Node: Other Versions1225653
-Node: Installation summary1232567
-Node: Notes1233769
-Node: Compatibility Mode1234563
-Node: Additions1235345
-Node: Accessing The Source1236270
-Node: Adding Code1237707
-Node: New Ports1243926
-Node: Derived Files1248414
-Ref: Derived Files-Footnote-11254060
-Ref: Derived Files-Footnote-21254095
-Ref: Derived Files-Footnote-31254693
-Node: Future Extensions1254807
-Node: Implementation Limitations1255465
-Node: Extension Design1256648
-Node: Old Extension Problems1257792
-Ref: Old Extension Problems-Footnote-11259310
-Node: Extension New Mechanism Goals1259367
-Ref: Extension New Mechanism Goals-Footnote-11262731
-Node: Extension Other Design Decisions1262920
-Node: Extension Future Growth1265033
-Node: Notes summary1265869
-Node: Basic Concepts1267044
-Node: Basic High Level1267725
-Ref: figure-general-flow1268007
-Ref: figure-process-flow1268692
-Ref: Basic High Level-Footnote-11271993
-Node: Basic Data Typing1272178
-Node: Glossary1275506
-Node: Copying1307344
-Node: GNU Free Documentation License1344887
-Node: Index1370007
+Node: Foreword344133
+Node: Foreword448575
+Node: Preface50107
+Ref: Preface-Footnote-152966
+Ref: Preface-Footnote-253073
+Ref: Preface-Footnote-353307
+Node: History53449
+Node: Names55801
+Ref: Names-Footnote-156895
+Node: This Manual57042
+Ref: This Manual-Footnote-163681
+Node: Conventions63781
+Node: Manual History66136
+Ref: Manual History-Footnote-169133
+Ref: Manual History-Footnote-269174
+Node: How To Contribute69248
+Node: Acknowledgments70174
+Node: Getting Started75082
+Node: Running gawk77521
+Node: One-shot78711
+Node: Read Terminal79974
+Node: Long81967
+Node: Executable Scripts83480
+Ref: Executable Scripts-Footnote-186275
+Node: Comments86378
+Node: Quoting88862
+Node: DOS Quoting94379
+Node: Sample Data Files96435
+Node: Very Simple99030
+Node: Two Rules103932
+Node: More Complex105817
+Node: Statements/Lines108683
+Ref: Statements/Lines-Footnote-1113142
+Node: Other Features113407
+Node: When114343
+Ref: When-Footnote-1116097
+Node: Intro Summary116162
+Node: Invoking Gawk117046
+Node: Command Line118560
+Node: Options119358
+Ref: Options-Footnote-1136436
+Ref: Options-Footnote-2136667
+Node: Other Arguments136692
+Node: Naming Standard Input139639
+Node: Environment Variables140849
+Node: AWKPATH Variable141407
+Ref: AWKPATH Variable-Footnote-1144819
+Ref: AWKPATH Variable-Footnote-2144853
+Node: AWKLIBPATH Variable145114
+Node: Other Environment Variables146772
+Node: Exit Status150593
+Node: Include Files151270
+Node: Loading Shared Libraries154960
+Node: Obsolete156388
+Node: Undocumented157080
+Node: Invoking Summary157377
+Node: Regexp159037
+Node: Regexp Usage160491
+Node: Escape Sequences162528
+Node: Regexp Operators168760
+Ref: Regexp Operators-Footnote-1176176
+Ref: Regexp Operators-Footnote-2176323
+Node: Bracket Expressions176421
+Ref: table-char-classes178897
+Node: Leftmost Longest182223
+Node: Computed Regexps183526
+Node: GNU Regexp Operators186953
+Node: Case-sensitivity190632
+Ref: Case-sensitivity-Footnote-1193519
+Ref: Case-sensitivity-Footnote-2193754
+Node: Regexp Summary193862
+Node: Reading Files195328
+Node: Records197597
+Node: awk split records198672
+Node: gawk split records203947
+Ref: gawk split records-Footnote-1208533
+Node: Fields208570
+Node: Nonconstant Fields211311
+Ref: Nonconstant Fields-Footnote-1213547
+Node: Changing Fields213751
+Node: Field Separators219782
+Node: Default Field Splitting222480
+Node: Regexp Field Splitting223598
+Node: Single Character Fields226951
+Node: Command Line Field Separator228011
+Node: Full Line Fields231229
+Ref: Full Line Fields-Footnote-1232751
+Ref: Full Line Fields-Footnote-2232797
+Node: Field Splitting Summary232898
+Node: Constant Size234972
+Node: Fixed width data235704
+Node: Skipping intervening239171
+Node: Allowing trailing data239969
+Node: Fields with fixed data241006
+Node: Splitting By Content242524
+Ref: Splitting By Content-Footnote-1246174
+Node: Testing field creation246337
+Node: Multiple Line247962
+Ref: Multiple Line-Footnote-1253846
+Node: Getline254025
+Node: Plain Getline256494
+Node: Getline/Variable259135
+Node: Getline/File260286
+Node: Getline/Variable/File261674
+Ref: Getline/Variable/File-Footnote-1263279
+Node: Getline/Pipe263367
+Node: Getline/Variable/Pipe266074
+Node: Getline/Coprocess267209
+Node: Getline/Variable/Coprocess268476
+Node: Getline Notes269218
+Node: Getline Summary272015
+Ref: table-getline-variants272439
+Node: Read Timeout273187
+Ref: Read Timeout-Footnote-1277093
+Node: Retrying Input277151
+Node: Command-line directories278350
+Node: Input Summary279256
+Node: Input Exercises282428
+Node: Printing283156
+Node: Print284990
+Node: Print Examples286447
+Node: Output Separators289227
+Node: OFMT291244
+Node: Printf292600
+Node: Basic Printf293385
+Node: Control Letters294959
+Node: Format Modifiers300121
+Node: Printf Examples306136
+Node: Redirection308622
+Node: Special FD315463
+Ref: Special FD-Footnote-1318631
+Node: Special Files318705
+Node: Other Inherited Files319322
+Node: Special Network320323
+Node: Special Caveats321183
+Node: Close Files And Pipes322132
+Ref: table-close-pipe-return-values329039
+Ref: Close Files And Pipes-Footnote-1329852
+Ref: Close Files And Pipes-Footnote-2330000
+Node: Nonfatal330152
+Node: Output Summary332490
+Node: Output Exercises333712
+Node: Expressions334391
+Node: Values335579
+Node: Constants336257
+Node: Scalar Constants336948
+Ref: Scalar Constants-Footnote-1339472
+Node: Nondecimal-numbers339722
+Node: Regexp Constants342723
+Node: Using Constant Regexps343249
+Node: Standard Regexp Constants343871
+Node: Strong Regexp Constants347059
+Node: Variables350017
+Node: Using Variables350674
+Node: Assignment Options352584
+Node: Conversion355051
+Node: Strings And Numbers355575
+Ref: Strings And Numbers-Footnote-1358638
+Node: Locale influences conversions358747
+Ref: table-locale-affects361505
+Node: All Operators362123
+Node: Arithmetic Ops362752
+Node: Concatenation365258
+Ref: Concatenation-Footnote-1368105
+Node: Assignment Ops368212
+Ref: table-assign-ops373203
+Node: Increment Ops374516
+Node: Truth Values and Conditions377976
+Node: Truth Values379050
+Node: Typing and Comparison380098
+Node: Variable Typing380918
+Ref: Variable Typing-Footnote-1387381
+Ref: Variable Typing-Footnote-2387453
+Node: Comparison Operators387530
+Ref: table-relational-ops387949
+Node: POSIX String Comparison391444
+Ref: POSIX String Comparison-Footnote-1393139
+Ref: POSIX String Comparison-Footnote-2393278
+Node: Boolean Ops393362
+Ref: Boolean Ops-Footnote-1397844
+Node: Conditional Exp397936
+Node: Function Calls399672
+Node: Precedence403549
+Node: Locales407208
+Node: Expressions Summary408840
+Node: Patterns and Actions411413
+Node: Pattern Overview412533
+Node: Regexp Patterns414210
+Node: Expression Patterns414752
+Node: Ranges418533
+Node: BEGIN/END421641
+Node: Using BEGIN/END422402
+Ref: Using BEGIN/END-Footnote-1425138
+Node: I/O And BEGIN/END425244
+Node: BEGINFILE/ENDFILE427558
+Node: Empty430471
+Node: Using Shell Variables430788
+Node: Action Overview433062
+Node: Statements435387
+Node: If Statement437235
+Node: While Statement438730
+Node: Do Statement440758
+Node: For Statement441906
+Node: Switch Statement445077
+Node: Break Statement447463
+Node: Continue Statement449555
+Node: Next Statement451382
+Node: Nextfile Statement453765
+Node: Exit Statement456417
+Node: Built-in Variables458820
+Node: User-modified459953
+Node: Auto-set467720
+Ref: Auto-set-Footnote-1484527
+Ref: Auto-set-Footnote-2484733
+Node: ARGC and ARGV484789
+Node: Pattern Action Summary489002
+Node: Arrays491432
+Node: Array Basics492761
+Node: Array Intro493605
+Ref: figure-array-elements495580
+Ref: Array Intro-Footnote-1498284
+Node: Reference to Elements498412
+Node: Assigning Elements500876
+Node: Array Example501367
+Node: Scanning an Array503126
+Node: Controlling Scanning506148
+Ref: Controlling Scanning-Footnote-1511547
+Node: Numeric Array Subscripts511863
+Node: Uninitialized Subscripts514047
+Node: Delete515666
+Ref: Delete-Footnote-1518418
+Node: Multidimensional518475
+Node: Multiscanning521570
+Node: Arrays of Arrays523161
+Node: Arrays Summary527929
+Node: Functions530022
+Node: Built-in531060
+Node: Calling Built-in532141
+Node: Numeric Functions534137
+Ref: Numeric Functions-Footnote-1538165
+Ref: Numeric Functions-Footnote-2538810
+Ref: Numeric Functions-Footnote-3538858
+Node: String Functions539130
+Ref: String Functions-Footnote-1562988
+Ref: String Functions-Footnote-2563116
+Ref: String Functions-Footnote-3563364
+Node: Gory Details563451
+Ref: table-sub-escapes565242
+Ref: table-sub-proposed566761
+Ref: table-posix-sub568124
+Ref: table-gensub-escapes569665
+Ref: Gory Details-Footnote-1570488
+Node: I/O Functions570642
+Ref: table-system-return-values577110
+Ref: I/O Functions-Footnote-1579190
+Ref: I/O Functions-Footnote-2579338
+Node: Time Functions579458
+Ref: Time Functions-Footnote-1590129
+Ref: Time Functions-Footnote-2590197
+Ref: Time Functions-Footnote-3590355
+Ref: Time Functions-Footnote-4590466
+Ref: Time Functions-Footnote-5590578
+Ref: Time Functions-Footnote-6590805
+Node: Bitwise Functions591071
+Ref: table-bitwise-ops591665
+Ref: Bitwise Functions-Footnote-1597728
+Ref: Bitwise Functions-Footnote-2597901
+Node: Type Functions598092
+Node: I18N Functions600843
+Node: User-defined602494
+Node: Definition Syntax603306
+Ref: Definition Syntax-Footnote-1608993
+Node: Function Example609064
+Ref: Function Example-Footnote-1611986
+Node: Function Calling612008
+Node: Calling A Function612596
+Node: Variable Scope613554
+Node: Pass By Value/Reference616548
+Node: Function Caveats619192
+Ref: Function Caveats-Footnote-1621239
+Node: Return Statement621359
+Node: Dynamic Typing624338
+Node: Indirect Calls625268
+Ref: Indirect Calls-Footnote-1635520
+Node: Functions Summary635648
+Node: Library Functions638353
+Ref: Library Functions-Footnote-1641960
+Ref: Library Functions-Footnote-2642103
+Node: Library Names642274
+Ref: Library Names-Footnote-1645941
+Ref: Library Names-Footnote-2646164
+Node: General Functions646250
+Node: Strtonum Function647353
+Node: Assert Function650375
+Node: Round Function653701
+Node: Cliff Random Function655241
+Node: Ordinal Functions656257
+Ref: Ordinal Functions-Footnote-1659320
+Ref: Ordinal Functions-Footnote-2659572
+Node: Join Function659782
+Ref: Join Function-Footnote-1661552
+Node: Getlocaltime Function661752
+Node: Readfile Function665494
+Node: Shell Quoting667471
+Node: Data File Management668872
+Node: Filetrans Function669504
+Node: Rewind Function673600
+Node: File Checking675509
+Ref: File Checking-Footnote-1676843
+Node: Empty Files677044
+Node: Ignoring Assigns679023
+Node: Getopt Function680573
+Ref: Getopt Function-Footnote-1692042
+Node: Passwd Functions692242
+Ref: Passwd Functions-Footnote-1701081
+Node: Group Functions701169
+Ref: Group Functions-Footnote-1709067
+Node: Walking Arrays709274
+Node: Library Functions Summary712282
+Node: Library Exercises713688
+Node: Sample Programs714153
+Node: Running Examples714923
+Node: Clones715651
+Node: Cut Program716875
+Node: Egrep Program726804
+Ref: Egrep Program-Footnote-1734316
+Node: Id Program734426
+Node: Split Program738106
+Ref: Split Program-Footnote-1741564
+Node: Tee Program741693
+Node: Uniq Program744483
+Node: Wc Program752104
+Ref: Wc Program-Footnote-1756359
+Node: Miscellaneous Programs756453
+Node: Dupword Program757666
+Node: Alarm Program759696
+Node: Translate Program764551
+Ref: Translate Program-Footnote-1769116
+Node: Labels Program769386
+Ref: Labels Program-Footnote-1772737
+Node: Word Sorting772821
+Node: History Sorting776893
+Node: Extract Program778728
+Node: Simple Sed786782
+Node: Igawk Program789856
+Ref: Igawk Program-Footnote-1804187
+Ref: Igawk Program-Footnote-2804389
+Ref: Igawk Program-Footnote-3804511
+Node: Anagram Program804626
+Node: Signature Program807688
+Node: Programs Summary808935
+Node: Programs Exercises810149
+Ref: Programs Exercises-Footnote-1814278
+Node: Advanced Features814369
+Node: Nondecimal Data816359
+Node: Array Sorting817950
+Node: Controlling Array Traversal818650
+Ref: Controlling Array Traversal-Footnote-1827018
+Node: Array Sorting Functions827136
+Ref: Array Sorting Functions-Footnote-1832227
+Node: Two-way I/O832423
+Ref: Two-way I/O-Footnote-1840144
+Ref: Two-way I/O-Footnote-2840331
+Node: TCP/IP Networking840413
+Node: Profiling843531
+Node: Advanced Features Summary852549
+Node: Internationalization854393
+Node: I18N and L10N855873
+Node: Explaining gettext856560
+Ref: Explaining gettext-Footnote-1862452
+Ref: Explaining gettext-Footnote-2862637
+Node: Programmer i18n862802
+Ref: Programmer i18n-Footnote-1867751
+Node: Translator i18n867800
+Node: String Extraction868594
+Ref: String Extraction-Footnote-1869726
+Node: Printf Ordering869812
+Ref: Printf Ordering-Footnote-1872598
+Node: I18N Portability872662
+Ref: I18N Portability-Footnote-1875118
+Node: I18N Example875181
+Ref: I18N Example-Footnote-1878456
+Ref: I18N Example-Footnote-2878529
+Node: Gawk I18N878638
+Node: I18N Summary879283
+Node: Debugger880624
+Node: Debugging881624
+Node: Debugging Concepts882065
+Node: Debugging Terms883874
+Node: Awk Debugging886449
+Ref: Awk Debugging-Footnote-1887394
+Node: Sample Debugging Session887526
+Node: Debugger Invocation888060
+Node: Finding The Bug889446
+Node: List of Debugger Commands895920
+Node: Breakpoint Control897253
+Node: Debugger Execution Control900947
+Node: Viewing And Changing Data904309
+Node: Execution Stack907683
+Node: Debugger Info909320
+Node: Miscellaneous Debugger Commands913391
+Node: Readline Support918453
+Node: Limitations919349
+Node: Debugging Summary921458
+Node: Namespaces922737
+Node: Global Namespace923816
+Node: Qualified Names925214
+Node: Default Namespace926213
+Node: Changing The Namespace926954
+Node: Naming Rules928568
+Node: Internal Name Management930416
+Node: Namespace Example931458
+Node: Namespace And Features934020
+Node: Namespace Summary935455
+Node: Arbitrary Precision Arithmetic936932
+Node: Computer Arithmetic938419
+Ref: table-numeric-ranges942185
+Ref: table-floating-point-ranges942678
+Ref: Computer Arithmetic-Footnote-1943336
+Node: Math Definitions943393
+Ref: table-ieee-formats946709
+Ref: Math Definitions-Footnote-1947312
+Node: MPFR features947417
+Node: FP Math Caution949135
+Ref: FP Math Caution-Footnote-1950207
+Node: Inexactness of computations950576
+Node: Inexact representation951536
+Node: Comparing FP Values952896
+Node: Errors accumulate954137
+Node: Getting Accuracy955570
+Node: Try To Round958280
+Node: Setting precision959179
+Ref: table-predefined-precision-strings959876
+Node: Setting the rounding mode961706
+Ref: table-gawk-rounding-modes962080
+Ref: Setting the rounding mode-Footnote-1966011
+Node: Arbitrary Precision Integers966190
+Ref: Arbitrary Precision Integers-Footnote-1969365
+Node: Checking for MPFR969514
+Node: POSIX Floating Point Problems970988
+Ref: POSIX Floating Point Problems-Footnote-1975273
+Node: Floating point summary975311
+Node: Dynamic Extensions977501
+Node: Extension Intro979054
+Node: Plugin License980320
+Node: Extension Mechanism Outline981117
+Ref: figure-load-extension981556
+Ref: figure-register-new-function983121
+Ref: figure-call-new-function984213
+Node: Extension API Description986275
+Node: Extension API Functions Introduction987917
+Ref: table-api-std-headers989753
+Node: General Data Types993618
+Ref: General Data Types-Footnote-11001979
+Node: Memory Allocation Functions1002278
+Ref: Memory Allocation Functions-Footnote-11006488
+Node: Constructor Functions1006587
+Node: Registration Functions1010173
+Node: Extension Functions1010858
+Node: Exit Callback Functions1016180
+Node: Extension Version String1017430
+Node: Input Parsers1018093
+Node: Output Wrappers1030814
+Node: Two-way processors1035326
+Node: Printing Messages1037591
+Ref: Printing Messages-Footnote-11038762
+Node: Updating ERRNO1038915
+Node: Requesting Values1039654
+Ref: table-value-types-returned1040391
+Node: Accessing Parameters1041327
+Node: Symbol Table Access1042562
+Node: Symbol table by name1043074
+Ref: Symbol table by name-Footnote-11046098
+Node: Symbol table by cookie1046226
+Ref: Symbol table by cookie-Footnote-11050411
+Node: Cached values1050475
+Ref: Cached values-Footnote-11054011
+Node: Array Manipulation1054164
+Ref: Array Manipulation-Footnote-11055255
+Node: Array Data Types1055292
+Ref: Array Data Types-Footnote-11057950
+Node: Array Functions1058042
+Node: Flattening Arrays1062540
+Node: Creating Arrays1069516
+Node: Redirection API1074283
+Node: Extension API Variables1077116
+Node: Extension Versioning1077827
+Ref: gawk-api-version1078256
+Node: Extension GMP/MPFR Versioning1079987
+Node: Extension API Informational Variables1081615
+Node: Extension API Boilerplate1082688
+Node: Changes from API V11086662
+Node: Finding Extensions1088234
+Node: Extension Example1088793
+Node: Internal File Description1089591
+Node: Internal File Ops1093671
+Ref: Internal File Ops-Footnote-11105021
+Node: Using Internal File Ops1105161
+Ref: Using Internal File Ops-Footnote-11107544
+Node: Extension Samples1107818
+Node: Extension Sample File Functions1109347
+Node: Extension Sample Fnmatch1116996
+Node: Extension Sample Fork1118483
+Node: Extension Sample Inplace1119701
+Node: Extension Sample Ord1123005
+Node: Extension Sample Readdir1123841
+Ref: table-readdir-file-types1124730
+Node: Extension Sample Revout1125535
+Node: Extension Sample Rev2way1126124
+Node: Extension Sample Read write array1126864
+Node: Extension Sample Readfile1128806
+Node: Extension Sample Time1129901
+Node: Extension Sample API Tests1131249
+Node: gawkextlib1131741
+Node: Extension summary1134659
+Node: Extension Exercises1138361
+Node: Language History1139603
+Node: V7/SVR3.11141259
+Node: SVR41143411
+Node: POSIX1144845
+Node: BTL1146225
+Node: POSIX/GNU1146954
+Node: Feature History1152732
+Node: Common Extensions1168778
+Node: Ranges and Locales1170061
+Ref: Ranges and Locales-Footnote-11174677
+Ref: Ranges and Locales-Footnote-21174704
+Ref: Ranges and Locales-Footnote-31174939
+Node: Contributors1175160
+Node: History summary1181105
+Node: Installation1182485
+Node: Gawk Distribution1183429
+Node: Getting1183913
+Node: Extracting1184876
+Node: Distribution contents1186514
+Node: Unix Installation1192994
+Node: Quick Installation1193676
+Node: Shell Startup Files1196090
+Node: Additional Configuration Options1197179
+Node: Configuration Philosophy1199344
+Node: Non-Unix Installation1201713
+Node: PC Installation1202173
+Node: PC Binary Installation1203011
+Node: PC Compiling1203446
+Node: PC Using1204563
+Node: Cygwin1208116
+Node: MSYS1209215
+Node: VMS Installation1209716
+Node: VMS Compilation1210507
+Ref: VMS Compilation-Footnote-11211736
+Node: VMS Dynamic Extensions1211794
+Node: VMS Installation Details1213479
+Node: VMS Running1215732
+Node: VMS GNV1220011
+Node: VMS Old Gawk1220746
+Node: Bugs1221217
+Node: Bug address1221880
+Node: Usenet1224862
+Node: Maintainers1225866
+Node: Other Versions1227127
+Node: Installation summary1234041
+Node: Notes1235243
+Node: Compatibility Mode1236037
+Node: Additions1236819
+Node: Accessing The Source1237744
+Node: Adding Code1239181
+Node: New Ports1245400
+Node: Derived Files1249888
+Ref: Derived Files-Footnote-11255534
+Ref: Derived Files-Footnote-21255569
+Ref: Derived Files-Footnote-31256167
+Node: Future Extensions1256281
+Node: Implementation Limitations1256939
+Node: Extension Design1258122
+Node: Old Extension Problems1259266
+Ref: Old Extension Problems-Footnote-11260784
+Node: Extension New Mechanism Goals1260841
+Ref: Extension New Mechanism Goals-Footnote-11264205
+Node: Extension Other Design Decisions1264394
+Node: Extension Future Growth1266507
+Node: Notes summary1267343
+Node: Basic Concepts1268518
+Node: Basic High Level1269199
+Ref: figure-general-flow1269481
+Ref: figure-process-flow1270166
+Ref: Basic High Level-Footnote-11273467
+Node: Basic Data Typing1273652
+Node: Glossary1276980
+Node: Copying1308818
+Node: GNU Free Documentation License1346361
+Node: Index1371481
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index b08231df..7eb90db2 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -19,11 +19,6 @@
 * awk: (gawk)Invoking Gawk.                     Text scanning and processing.
 @end direntry
 
-@c Enable better indexing, requires texindex from Texinfo 6 or later.
-@tex
-\global\usebracesinindexestrue
-@end tex
-
 @ifset FOR_PRINT
 @tex
 \gdef\xrefprintnodename#1{``#1''}
@@ -772,10 +767,11 @@ particular records in a file and perform operations upon them.
                                         mean.
 * Function Example::                    An example function definition and
                                         what it does.
-* Function Caveats::                    Things to watch out for.
+* Function Calling::                    Calling user-defined functions.
 * Calling A Function::                  Don't use spaces.
 * Variable Scope::                      Controlling variable scope.
 * Pass By Value/Reference::             Passing parameters.
+* Function Caveats::                    Other points to know about functions.
 * Return Statement::                    Specifying the value a function
                                         returns.
 * Dynamic Typing::                      How variable types can change at
@@ -20499,7 +20495,7 @@ them (i.e., to tell @command{awk} what they should do).
 * Definition Syntax::           How to write definitions and what they mean.
 * Function Example::            An example function definition and what it
                                 does.
-* Function Caveats::            Things to watch out for.
+* Function Calling::            Calling user-defined functions.
 * Return Statement::            Specifying the value a function returns.
 * Dynamic Typing::              How variable types can change at runtime.
 @end menu
@@ -20773,7 +20769,7 @@ for its format string. That would be a mistake, because @code{ctime()} is
 supposed to return the time formatted in a standard fashion, and user-level
 code could have changed @code{PROCINFO["strftime"]}.
 
-@node Function Caveats
+@node Function Calling
 @subsection Calling User-Defined Functions
 
 @cindex functions, user-defined, calling
@@ -20785,6 +20781,7 @@ the function.
 * Calling A Function::          Don't use spaces.
 * Variable Scope::              Controlling variable scope.
 * Pass By Value/Reference::     Passing parameters.
+* Function Caveats::            Other points to know about functions.
 @end menu
 
 @node Calling A Function
@@ -21031,6 +21028,9 @@ prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because
 @code{changeit()} stores @code{"two"} in the second element of @code{a}.
 @end quotation
 
+@node Function Caveats
+@subsubsection Other Points About Calling Functions
+
 @cindex undefined functions
 @cindex functions, undefined
 Some @command{awk} implementations allow you to call a function that
@@ -21072,6 +21072,36 @@ or the @code{nextfile} statement
 inside a user-defined function.
 @command{gawk} does not have this limitation.
 
+You can call a function and pass it more parameters than it was declared
+with, like so:
+
+@example
+function foo(p1, p2)
+@{
+    @dots{}
+@}
+
+BEGIN @{
+    foo(1, 2, 3, 4)
+@}
+@end example
+
+Doing so is bad practice, however.  The called function cannot do
+anything with the additional values being passed to it, so @command{awk}
+evaluates the expressions but then just throws them away.
+
+More importantly, such a call is confusing for whoever will next read your
+program.@footnote{Said person might even be you, sometime in the future,
+at which point you will wonder, ``what was I thinking?!?''} Function
+parameters generally are input items that influence the computation
+performed by the function.  Calling a function with more paramaters than
+it accepts gives the false impression that those values are important
+to the function, when in fact they are not.
+
+Because this is such a bad practice, @command{gawk} @emph{unconditionally}
+issues a warning whenever it executes such a function call.  (If you
+don't like the warning, fix your code!  It's incorrect, after all.)
+
 @node Return Statement
 @subsection The @code{return} Statement
 @cindex @code{return} statement@comma{} user-defined functions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index cee76105..49bb7ca0 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -762,10 +762,11 @@ particular records in a file and perform operations upon them.
                                         mean.
 * Function Example::                    An example function definition and
                                         what it does.
-* Function Caveats::                    Things to watch out for.
+* Function Calling::                    Calling user-defined functions.
 * Calling A Function::                  Don't use spaces.
 * Variable Scope::                      Controlling variable scope.
 * Pass By Value/Reference::             Passing parameters.
+* Function Caveats::                    Other points to know about functions.
 * Return Statement::                    Specifying the value a function
                                         returns.
 * Dynamic Typing::                      How variable types can change at
@@ -19536,7 +19537,7 @@ them (i.e., to tell @command{awk} what they should do).
 * Definition Syntax::           How to write definitions and what they mean.
 * Function Example::            An example function definition and what it
                                 does.
-* Function Caveats::            Things to watch out for.
+* Function Calling::            Calling user-defined functions.
 * Return Statement::            Specifying the value a function returns.
 * Dynamic Typing::              How variable types can change at runtime.
 @end menu
@@ -19810,7 +19811,7 @@ for its format string. That would be a mistake, because @code{ctime()} is
 supposed to return the time formatted in a standard fashion, and user-level
 code could have changed @code{PROCINFO["strftime"]}.
 
-@node Function Caveats
+@node Function Calling
 @subsection Calling User-Defined Functions
 
 @cindex functions, user-defined, calling
@@ -19822,6 +19823,7 @@ the function.
 * Calling A Function::          Don't use spaces.
 * Variable Scope::              Controlling variable scope.
 * Pass By Value/Reference::     Passing parameters.
+* Function Caveats::            Other points to know about functions.
 @end menu
 
 @node Calling A Function
@@ -20068,6 +20070,9 @@ prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because
 @code{changeit()} stores @code{"two"} in the second element of @code{a}.
 @end quotation
 
+@node Function Caveats
+@subsubsection Other Points About Calling Functions
+
 @cindex undefined functions
 @cindex functions, undefined
 Some @command{awk} implementations allow you to call a function that
@@ -20109,6 +20114,36 @@ or the @code{nextfile} statement
 inside a user-defined function.
 @command{gawk} does not have this limitation.
 
+You can call a function and pass it more parameters than it was declared
+with, like so:
+
+@example
+function foo(p1, p2)
+@{
+    @dots{}
+@}
+
+BEGIN @{
+    foo(1, 2, 3, 4)
+@}
+@end example
+
+Doing so is bad practice, however.  The called function cannot do
+anything with the additional values being passed to it, so @command{awk}
+evaluates the expressions but then just throws them away.
+
+More importantly, such a call is confusing for whoever will next read your
+program.@footnote{Said person might even be you, sometime in the future,
+at which point you will wonder, ``what was I thinking?!?''} Function
+parameters generally are input items that influence the computation
+performed by the function.  Calling a function with more paramaters than
+it accepts gives the false impression that those values are important
+to the function, when in fact they are not.
+
+Because this is such a bad practice, @command{gawk} @emph{unconditionally}
+issues a warning whenever it executes such a function call.  (If you
+don't like the warning, fix your code!  It's incorrect, after all.)
+
 @node Return Statement
 @subsection The @code{return} Statement
 @cindex @code{return} statement@comma{} user-defined functions