More doc fixes.

3 files changed, 669 insertions, 422 deletions

diff --git a/TODO b/TODO
index 9ec8e55e..02dbcc28 100644
--- a/TODO
+++ b/TODO
@@ -28,7 +28,7 @@ xgawk features (@load, -l, others)
 #	- use of STRCOLL for comparison
 Add tests for pgawk
 Add tests for patches in emails
-Add doc fix in email
+#Add doc fix in email
 #Update debugger chapter with new features
 Add debugger commands to reference card
 #Remove obsolete directories
diff --git a/doc/gawk.info b/doc/gawk.info
index bd4f7f95..3c7816c7 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -323,6 +323,9 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
 * Function Example::               An example function definition and what it
                                    does.
 * Function Caveats::               Things to watch out for.
+* Calling A Function::             Don't use blanks.
+* Variable Scope::                 Controlling variable scope.
+* Pass By Value/Reference::        Passing parameters.
 * Return Statement::               Specifying the value a function returns.
 * Dynamic Typing::                 How variable types can change at runtime.
 * Indirect Calls::                 Choosing the function to call at runtime.
@@ -11318,6 +11321,20 @@ File: gawk.info,  Node: Function Caveats,  Next: Return Statement,  Prev: Functi
 8.2.3 Calling User-Defined Functions
 ------------------------------------
 
+This section describes how to call a user-defined function.
+
+* Menu:
+
+* Calling A Function::       Don't use blanks.
+* Variable Scope::           Controlling variable scope.
+* Pass By Value/Reference::  Passing parameters.
+
+
+File: gawk.info,  Node: Calling A Function,  Next: Variable Scope,  Up: Function Caveats
+
+8.2.3.1 Writing A Function Call
+...............................
+
 "Calling a function" means causing the function to run and do its job.
 A function call is an expression and its value is the value returned by
 the function.
@@ -11338,8 +11355,106 @@ concatenate a variable with an expression in parentheses.  However, it
 notices that you used a function name and not a variable name, and
 reports an error.
 
-   When a function is called, it is given a _copy_ of the values of its
-arguments.  This is known as "call by value".  The caller may use a
+
+File: gawk.info,  Node: Variable Scope,  Next: Pass By Value/Reference,  Prev: Calling A Function,  Up: Function Caveats
+
+8.2.3.2 Controlling Variable Scope
+..................................
+
+There is no way to make a variable local to a `{ ... }' block in `awk',
+but you can make a variable local to a function. It is good practice to
+do so whenever a variable is needed only in that function.
+
+   To make a variable local to a function, simply declare the variable
+as an argument after the actual function arguments (*note Definition
+Syntax::).  Look at the following example where variable `i' is a
+global variable used by both functions `foo()' and `bar()':
+
+     function bar()
+     {
+         for (i = 0; i < 3; i++)
+             print "bar's i=" i
+     }
+     function foo(j)
+     {
+         i = j + 1
+         print "foo's i=" i
+         bar()
+         print "foo's i=" i
+     }
+
+     BEGIN {
+           i = 10
+           print "top's i=" i
+           foo(0)
+           print "top's i=" i
+     }
+
+   Running this script produces the following, because the `i' in
+functions `foo()' and `bar()' and at the top level refer to the same
+variable instance:
+
+     top's i=10
+     foo's i=1
+     bar's i=0
+     bar's i=1
+     bar's i=2
+     foo's i=3
+     foo's i=3
+     top's i=3
+
+   If you want `i' to be local to both `foo()' and `bar()' do as
+follows (the extra-space before `i' is a coding convention to indicate
+that `i' is a local variable, not an argument):
+
+     function bar(    i)
+     {
+         for (i = 0; i < 3; i++)
+             print "bar's i=" i
+     }
+     function foo(j,    i)
+     {
+         i = j + 1
+         print "foo's i=" i
+         bar()
+         print "foo's i=" i
+     }
+
+     BEGIN {
+           i = 10
+           foo(0)
+     }
+
+   Running the corrected script produces the following:
+
+     top's i=10
+     bar's i=1
+     foo's i=0
+     foo's i=1
+     foo's i=2
+     bar's i=1
+     top's i=10
+
+
+File: gawk.info,  Node: Pass By Value/Reference,  Prev: Variable Scope,  Up: Function Caveats
+
+8.2.3.3 Passing Function Arguments By Value Or By Reference
+...........................................................
+
+In `awk', when you declare a function, there is no way to declare
+explicitly whether the arguments are passed "by value" or "by
+reference".
+
+   Instead the passing convention is determined at runtime when the
+function is called according to the following rule:
+
+   * If the argument is an array variable, then it is passed by
+     reference,
+
+   * Otherwise the argument is passed by value.
+
+   Passing an argument by value means that when a function is called, it
+is given a _copy_ of the value of this argument.  The caller may use a
 variable as the expression for the argument, but the called function
 does not know this--it only knows what value the argument had.  For
 example, if you write the following code:
@@ -11355,9 +11470,9 @@ variables, this has no effect on any other variables.  Thus, if
 
      function myfunc(str)
      {
-       print str
-       str = "zzz"
-       print str
+        print str
+        str = "zzz"
+        print str
      }
 
 to change its first argument variable `str', it does _not_ change the
@@ -24522,7 +24637,8 @@ Index
 * arguments, retrieving:                 Internals.           (line 111)
 * arithmetic operators:                  Arithmetic Ops.      (line   6)
 * arrays:                                Arrays.              (line   6)
-* arrays, as parameters to functions:    Function Caveats.    (line  55)
+* arrays, as parameters to functions:    Pass By Value/Reference.
+                                                              (line  47)
 * arrays, associative:                   Array Intro.         (line  50)
 * arrays, associative, clearing:         Internals.           (line  66)
 * arrays, associative, library functions and: Library Names.  (line  57)
@@ -24773,8 +24889,10 @@ Index
 * built-in variables, -v option, setting with: Options.       (line  38)
 * built-in variables, conveying information: Auto-set.        (line   6)
 * built-in variables, user-modifiable:   User-modified.       (line   6)
-* call by reference:                     Function Caveats.    (line  55)
-* call by value:                         Function Caveats.    (line  26)
+* call by reference:                     Pass By Value/Reference.
+                                                              (line  47)
+* call by value:                         Pass By Value/Reference.
+                                                              (line  18)
 * caret (^) <1>:                         GNU Regexp Operators.
                                                               (line  59)
 * caret (^):                             Regexp Operators.    (line  22)
@@ -25452,7 +25570,8 @@ Index
 * function calls:                        Function Calls.      (line   6)
 * function calls, indirect:              Indirect Calls.      (line   6)
 * function pointers:                     Indirect Calls.      (line   6)
-* functions, arrays as parameters to:    Function Caveats.    (line  55)
+* functions, arrays as parameters to:    Pass By Value/Reference.
+                                                              (line  47)
 * functions, built-in <1>:               Functions.           (line   6)
 * functions, built-in:                   Function Calls.      (line  10)
 * functions, built-in, adding to gawk:   Dynamic Extensions.  (line  10)
@@ -25486,9 +25605,10 @@ Index
 * functions, recursive:                  Definition Syntax.   (line  73)
 * functions, return values, setting:     Internals.           (line 136)
 * functions, string-translation:         I18N Functions.      (line   6)
-* functions, undefined:                  Function Caveats.    (line  79)
+* functions, undefined:                  Pass By Value/Reference.
+                                                              (line  71)
 * functions, user-defined:               User-defined.        (line   6)
-* functions, user-defined, calling:      Function Caveats.    (line   6)
+* functions, user-defined, calling:      Calling A Function.  (line   6)
 * functions, user-defined, counts:       Profiling.           (line 132)
 * functions, user-defined, library of:   Library Functions.   (line   6)
 * functions, user-defined, next/nextfile statements and <1>: Nextfile Statement.
@@ -25844,7 +25964,8 @@ Index
 * lint checking, issuing warnings:       Options.             (line 141)
 * lint checking, POSIXLY_CORRECT environment variable: Options.
                                                               (line 287)
-* lint checking, undefined functions:    Function Caveats.    (line  96)
+* lint checking, undefined functions:    Pass By Value/Reference.
+                                                              (line  88)
 * LINT variable:                         User-modified.       (line  98)
 * Linux <1>:                             Glossary.            (line 582)
 * Linux <2>:                             Atari Compiling.     (line  16)
@@ -25852,6 +25973,7 @@ Index
 * Linux:                                 Manual History.      (line  28)
 * list debugger command:                 Miscellaneous Dgawk Commands.
                                                               (line  77)
+* local variables:                       Variable Scope.      (line   6)
 * locale categories:                     Explaining gettext.  (line  80)
 * locale decimal point character:        Options.             (line 216)
 * locale, definition of:                 Locales.             (line   6)
@@ -26141,8 +26263,8 @@ Index
 * portability, internationalization and: I18N Portability.    (line   6)
 * portability, length() function:        String Functions.    (line 146)
 * portability, new awk vs. old awk:      Conversion.          (line  54)
-* portability, next statement in user-defined functions: Function Caveats.
-                                                              (line  99)
+* portability, next statement in user-defined functions: Pass By Value/Reference.
+                                                              (line  91)
 * portability, NF variable, decrementing: Changing Fields.    (line 115)
 * portability, operators:                Increment Ops.       (line  61)
 * portability, operators, not in POSIX awk: Precedence.       (line  98)
@@ -26688,7 +26810,8 @@ Index
 * type internal variable:                Internals.           (line  58)
 * u debugger command (alias for until):  Dgawk Execution Control.
                                                               (line  83)
-* undefined functions:                   Function Caveats.    (line  79)
+* undefined functions:                   Pass By Value/Reference.
+                                                              (line  71)
 * underscore (_), _ C macro:             Explaining gettext.  (line  70)
 * underscore (_), in names of private variables: Library Names.
                                                               (line  29)
@@ -26747,6 +26870,7 @@ Index
 * variables, global, for library functions: Library Names.    (line  11)
 * variables, global, printing list of:   Options.             (line  88)
 * variables, initializing:               Using Variables.     (line  20)
+* variables, local:                      Variable Scope.      (line   6)
 * variables, names of:                   Arrays.              (line  18)
 * variables, private:                    Library Names.       (line  11)
 * variables, setting:                    Options.             (line  30)
@@ -26836,402 +26960,405 @@ Index
 
 Tag Table:
 Node: Top1340
-Node: Foreword29942
-Node: Preface34258
-Ref: Preface-Footnote-137210
-Ref: Preface-Footnote-237316
-Node: History37548
-Node: Names39780
-Ref: Names-Footnote-141257
-Node: This Manual41329
-Ref: This Manual-Footnote-146227
-Node: Conventions46327
-Node: Manual History48386
-Ref: Manual History-Footnote-151564
-Ref: Manual History-Footnote-251605
-Node: How To Contribute51679
-Node: Acknowledgments52823
-Node: Getting Started57092
-Node: Running gawk59464
-Node: One-shot60650
-Node: Read Terminal61875
-Ref: Read Terminal-Footnote-163525
-Ref: Read Terminal-Footnote-263799
-Node: Long63970
-Node: Executable Scripts65346
-Ref: Executable Scripts-Footnote-167207
-Ref: Executable Scripts-Footnote-267309
-Node: Comments67760
-Node: Quoting70128
-Node: DOS Quoting74745
-Node: Sample Data Files75413
-Node: Very Simple78445
-Node: Two Rules83042
-Node: More Complex85189
-Ref: More Complex-Footnote-188119
-Node: Statements/Lines88199
-Ref: Statements/Lines-Footnote-192555
-Node: Other Features92820
-Node: When93689
-Node: Regexp95832
-Node: Regexp Usage97286
-Node: Escape Sequences99312
-Node: Regexp Operators105055
-Ref: Regexp Operators-Footnote-1112227
-Ref: Regexp Operators-Footnote-2112374
-Node: Character Lists112472
-Ref: table-char-classes114247
-Node: GNU Regexp Operators116872
-Node: Case-sensitivity120585
-Ref: Case-sensitivity-Footnote-1123540
-Ref: Case-sensitivity-Footnote-2123775
-Node: Leftmost Longest123883
-Node: Computed Regexps125084
-Node: Locales128501
-Node: Reading Files131591
-Node: Records133532
-Ref: Records-Footnote-1142098
-Node: Fields142135
-Ref: Fields-Footnote-1145167
-Node: Nonconstant Fields145253
-Node: Changing Fields147455
-Node: Field Separators152740
-Node: Default Field Splitting155369
-Node: Regexp Field Splitting156486
-Node: Single Character Fields159836
-Node: Command Line Field Separator160887
-Node: Field Splitting Summary164326
-Ref: Field Splitting Summary-Footnote-1167512
-Node: Constant Size167613
-Node: Splitting By Content172084
-Ref: Splitting By Content-Footnote-1175686
-Node: Multiple Line175726
-Ref: Multiple Line-Footnote-1181466
-Node: Getline181645
-Node: Plain Getline183873
-Node: Getline/Variable185962
-Node: Getline/File187103
-Node: Getline/Variable/File188425
-Ref: Getline/Variable/File-Footnote-1190024
-Node: Getline/Pipe190111
-Node: Getline/Variable/Pipe192659
-Node: Getline/Coprocess193766
-Node: Getline/Variable/Coprocess195009
-Node: Getline Notes195723
-Node: Getline Summary197665
-Ref: table-getline-variants197949
-Node: Command line directories198854
-Node: Printing199479
-Node: Print201110
-Node: Print Examples202447
-Node: Output Separators205231
-Node: OFMT206990
-Node: Printf208348
-Node: Basic Printf209254
-Node: Control Letters210791
-Node: Format Modifiers214603
-Node: Printf Examples220614
-Node: Redirection223329
-Node: Special Files230307
-Node: Special FD230840
-Ref: Special FD-Footnote-1234415
-Node: Special Network234489
-Node: Special Caveats235344
-Node: Close Files And Pipes236138
-Ref: Close Files And Pipes-Footnote-1243082
-Ref: Close Files And Pipes-Footnote-2243230
-Node: Expressions243380
-Node: Values244449
-Node: Constants245125
-Node: Scalar Constants245805
-Ref: Scalar Constants-Footnote-1246664
-Node: Nondecimal-numbers246846
-Node: Regexp Constants249905
-Node: Using Constant Regexps250380
-Node: Variables253385
-Node: Using Variables254040
-Node: Assignment Options255767
-Node: Conversion257648
-Ref: table-locale-affects263022
-Ref: Conversion-Footnote-1263646
-Node: All Operators263755
-Node: Arithmetic Ops264385
-Node: Concatenation266884
-Ref: Concatenation-Footnote-1269677
-Node: Assignment Ops269796
-Ref: table-assign-ops274784
-Node: Increment Ops276185
-Node: Truth Values and Conditions279663
-Node: Truth Values280746
-Node: Typing and Comparison281794
-Node: Variable Typing282583
-Ref: Variable Typing-Footnote-1286480
-Node: Comparison Operators286602
-Ref: table-relational-ops287012
-Node: POSIX String Comparison290561
-Ref: POSIX String Comparison-Footnote-1291518
-Node: Boolean Ops291656
-Ref: Boolean Ops-Footnote-1295734
-Node: Conditional Exp295825
-Node: Function Calls297557
-Node: Precedence301116
-Node: Patterns and Actions304769
-Node: Pattern Overview305823
-Node: Regexp Patterns307489
-Node: Expression Patterns308032
-Node: Ranges311606
-Node: BEGIN/END314572
-Node: Using BEGIN/END315322
-Ref: Using BEGIN/END-Footnote-1318053
-Node: I/O And BEGIN/END318167
-Node: Empty320436
-Node: BEGINFILE/ENDFILE320770
-Node: Using Shell Variables323595
-Node: Action Overview325874
-Node: Statements328231
-Node: If Statement330090
-Node: While Statement331589
-Node: Do Statement333633
-Node: For Statement334789
-Node: Switch Statement337941
-Node: Break Statement340038
-Node: Continue Statement342014
-Node: Next Statement343715
-Node: Nextfile Statement346097
-Node: Exit Statement348615
-Node: Built-in Variables350890
-Node: User-modified351985
-Ref: User-modified-Footnote-1359986
-Node: Auto-set360048
-Ref: Auto-set-Footnote-1368839
-Node: ARGC and ARGV369044
-Node: Arrays372803
-Node: Array Basics374374
-Node: Array Intro375085
-Node: Reference to Elements379403
-Node: Assigning Elements381673
-Node: Array Example382164
-Node: Scanning an Array383896
-Node: Delete386173
-Ref: Delete-Footnote-1388571
-Node: Numeric Array Subscripts388628
-Node: Uninitialized Subscripts390811
-Node: Multi-dimensional392439
-Node: Multi-scanning395530
-Node: Array Sorting397114
-Ref: Array Sorting-Footnote-1400312
-Node: Arrays of Arrays400506
-Node: Functions404614
-Node: Built-in405436
-Node: Calling Built-in406450
-Node: Numeric Functions408426
-Ref: Numeric Functions-Footnote-1412135
-Ref: Numeric Functions-Footnote-2412471
-Ref: Numeric Functions-Footnote-3412519
-Node: String Functions412788
-Ref: String Functions-Footnote-1434587
-Ref: String Functions-Footnote-2434716
-Ref: String Functions-Footnote-3434964
-Node: Gory Details435051
-Ref: table-sub-escapes436708
-Ref: table-posix-sub438022
-Ref: table-gensub-escapes438922
-Node: I/O Functions440093
-Ref: I/O Functions-Footnote-1446790
-Node: Time Functions446937
-Ref: Time Functions-Footnote-1457593
-Ref: Time Functions-Footnote-2457661
-Ref: Time Functions-Footnote-3457819
-Ref: Time Functions-Footnote-4457930
-Ref: Time Functions-Footnote-5458042
-Ref: Time Functions-Footnote-6458269
-Node: Bitwise Functions458535
-Ref: table-bitwise-ops459093
-Ref: Bitwise Functions-Footnote-1463253
-Node: I18N Functions463437
-Node: User-defined465067
-Node: Definition Syntax465871
-Ref: Definition Syntax-Footnote-1470501
-Node: Function Example470570
-Node: Function Caveats473164
-Node: Return Statement477107
-Node: Dynamic Typing480049
-Node: Indirect Calls480786
-Node: Internationalization490471
-Node: I18N and L10N491897
-Node: Explaining gettext492581
-Ref: Explaining gettext-Footnote-1497641
-Ref: Explaining gettext-Footnote-2497824
-Node: Programmer i18n497989
-Node: Translator i18n502250
-Node: String Extraction503041
-Ref: String Extraction-Footnote-1504000
-Node: Printf Ordering504086
-Ref: Printf Ordering-Footnote-1506868
-Node: I18N Portability506932
-Ref: I18N Portability-Footnote-1509379
-Node: I18N Example509442
-Ref: I18N Example-Footnote-1512075
-Node: Gawk I18N512147
-Node: Advanced Features512714
-Node: Nondecimal Data514029
-Node: Two-way I/O515590
-Ref: Two-way I/O-Footnote-1521004
-Node: TCP/IP Networking521081
-Node: Profiling523934
-Node: Invoking Gawk531334
-Node: Command Line532641
-Node: Options533426
-Ref: Options-Footnote-1546514
-Node: Other Arguments546539
-Node: AWKPATH Variable549220
-Ref: AWKPATH Variable-Footnote-1551995
-Node: Exit Status552255
-Node: Include Files552927
-Node: Obsolete556528
-Node: Undocumented557329
-Node: Known Bugs557591
-Node: Library Functions558193
-Ref: Library Functions-Footnote-1561174
-Node: Library Names561345
-Ref: Library Names-Footnote-1564818
-Ref: Library Names-Footnote-2565037
-Node: General Functions565123
-Node: Nextfile Function566186
-Node: Strtonum Function570550
-Node: Assert Function573491
-Node: Round Function576795
-Node: Cliff Random Function578335
-Node: Ordinal Functions579350
-Ref: Ordinal Functions-Footnote-1582410
-Node: Join Function582626
-Ref: Join Function-Footnote-1584388
-Node: Gettimeofday Function584588
-Node: Data File Management588299
-Node: Filetrans Function588931
-Node: Rewind Function592357
-Node: File Checking593803
-Node: Empty Files594833
-Node: Ignoring Assigns597058
-Node: Getopt Function598606
-Ref: Getopt Function-Footnote-1609888
-Node: Passwd Functions610091
-Ref: Passwd Functions-Footnote-1619069
-Node: Group Functions619157
-Node: Sample Programs627254
-Node: Running Examples627923
-Node: Clones628651
-Node: Cut Program629783
-Node: Egrep Program639542
-Ref: Egrep Program-Footnote-1647292
-Node: Id Program647402
-Node: Split Program651009
-Node: Tee Program654477
-Node: Uniq Program657220
-Node: Wc Program664587
-Ref: Wc Program-Footnote-1668831
-Node: Miscellaneous Programs669027
-Node: Dupword Program670147
-Node: Alarm Program672178
-Node: Translate Program676720
-Ref: Translate Program-Footnote-1681099
-Ref: Translate Program-Footnote-2681336
-Node: Labels Program681470
-Ref: Labels Program-Footnote-1684761
-Node: Word Sorting684845
-Node: History Sorting689192
-Node: Extract Program691030
-Node: Simple Sed698388
-Node: Igawk Program701445
-Ref: Igawk Program-Footnote-1716176
-Ref: Igawk Program-Footnote-2716377
-Node: Signature Program716515
-Node: Debugger717595
-Node: Debugging718471
-Node: Debugging Concepts718785
-Node: Debugging Terms720638
-Node: Awk Debugging723186
-Node: Sample dgawk session724078
-Node: dgawk invocation724570
-Node: Finding The Bug725754
-Node: List of Debugger Commands732269
-Node: Breakpoint Control733584
-Node: Dgawk Execution Control736794
-Node: Viewing And Changing Data740143
-Node: Dgawk Stack743439
-Node: Dgawk Info744900
-Node: Miscellaneous Dgawk Commands748838
-Node: Readline Support754554
-Node: Dgawk Limitations755370
-Node: Language History757542
-Node: V7/SVR3.1758919
-Node: SVR4761214
-Node: POSIX762659
-Node: BTL764371
-Node: POSIX/GNU766061
-Node: Contributors775725
-Node: Installation779334
-Node: Gawk Distribution780305
-Node: Getting780789
-Node: Extracting781615
-Node: Distribution contents783003
-Node: Unix Installation788076
-Node: Quick Installation788667
-Node: Additional Configuration Options790369
-Node: Configuration Philosophy792132
-Node: Non-Unix Installation794496
-Node: PC Installation794961
-Node: PC Binary Installation796267
-Node: PC Compiling798110
-Node: PC Dynamic802615
-Node: PC Using804978
-Node: Cygwin809526
-Node: MSYS810510
-Node: VMS Installation811016
-Node: VMS Compilation811620
-Node: VMS Installation Details813197
-Node: VMS Running814827
-Node: VMS POSIX816424
-Node: VMS Old Gawk817722
-Node: Unsupported818191
-Node: Atari Installation818653
-Node: Atari Compiling819940
-Node: Atari Using821829
-Node: BeOS Installation824676
-Node: Tandem Installation825821
-Node: Bugs827500
-Node: Other Versions831332
-Node: Notes836554
-Node: Compatibility Mode837246
-Node: Additions838029
-Node: Adding Code838779
-Node: New Ports844831
-Node: Dynamic Extensions848963
-Node: Internals850344
-Node: Plugin License860749
-Node: Sample Library861383
-Node: Internal File Description862047
-Node: Internal File Ops865742
-Ref: Internal File Ops-Footnote-1870618
-Node: Using Internal File Ops870766
-Node: Future Extensions872791
-Node: Basic Concepts876828
-Node: Basic High Level877585
-Ref: Basic High Level-Footnote-1881704
-Node: Basic Data Typing881898
-Node: Floating Point Issues886335
-Node: String Conversion Precision887418
-Ref: String Conversion Precision-Footnote-1889112
-Node: Unexpected Results889221
-Node: POSIX Floating Point Problems891047
-Ref: POSIX Floating Point Problems-Footnote-1894746
-Node: Glossary894784
-Node: Copying918552
-Node: GNU Free Documentation License956109
-Node: next-edition981253
-Node: unresolved981605
-Node: revision982105
-Node: consistency982528
-Node: Index985881
+Node: Foreword30113
+Node: Preface34429
+Ref: Preface-Footnote-137381
+Ref: Preface-Footnote-237487
+Node: History37719
+Node: Names39951
+Ref: Names-Footnote-141428
+Node: This Manual41500
+Ref: This Manual-Footnote-146398
+Node: Conventions46498
+Node: Manual History48557
+Ref: Manual History-Footnote-151735
+Ref: Manual History-Footnote-251776
+Node: How To Contribute51850
+Node: Acknowledgments52994
+Node: Getting Started57263
+Node: Running gawk59635
+Node: One-shot60821
+Node: Read Terminal62046
+Ref: Read Terminal-Footnote-163696
+Ref: Read Terminal-Footnote-263970
+Node: Long64141
+Node: Executable Scripts65517
+Ref: Executable Scripts-Footnote-167378
+Ref: Executable Scripts-Footnote-267480
+Node: Comments67931
+Node: Quoting70299
+Node: DOS Quoting74916
+Node: Sample Data Files75584
+Node: Very Simple78616
+Node: Two Rules83213
+Node: More Complex85360
+Ref: More Complex-Footnote-188290
+Node: Statements/Lines88370
+Ref: Statements/Lines-Footnote-192726
+Node: Other Features92991
+Node: When93860
+Node: Regexp96003
+Node: Regexp Usage97457
+Node: Escape Sequences99483
+Node: Regexp Operators105226
+Ref: Regexp Operators-Footnote-1112398
+Ref: Regexp Operators-Footnote-2112545
+Node: Character Lists112643
+Ref: table-char-classes114418
+Node: GNU Regexp Operators117043
+Node: Case-sensitivity120756
+Ref: Case-sensitivity-Footnote-1123711
+Ref: Case-sensitivity-Footnote-2123946
+Node: Leftmost Longest124054
+Node: Computed Regexps125255
+Node: Locales128672
+Node: Reading Files131762
+Node: Records133703
+Ref: Records-Footnote-1142269
+Node: Fields142306
+Ref: Fields-Footnote-1145338
+Node: Nonconstant Fields145424
+Node: Changing Fields147626
+Node: Field Separators152911
+Node: Default Field Splitting155540
+Node: Regexp Field Splitting156657
+Node: Single Character Fields160007
+Node: Command Line Field Separator161058
+Node: Field Splitting Summary164497
+Ref: Field Splitting Summary-Footnote-1167683
+Node: Constant Size167784
+Node: Splitting By Content172255
+Ref: Splitting By Content-Footnote-1175857
+Node: Multiple Line175897
+Ref: Multiple Line-Footnote-1181637
+Node: Getline181816
+Node: Plain Getline184044
+Node: Getline/Variable186133
+Node: Getline/File187274
+Node: Getline/Variable/File188596
+Ref: Getline/Variable/File-Footnote-1190195
+Node: Getline/Pipe190282
+Node: Getline/Variable/Pipe192830
+Node: Getline/Coprocess193937
+Node: Getline/Variable/Coprocess195180
+Node: Getline Notes195894
+Node: Getline Summary197836
+Ref: table-getline-variants198120
+Node: Command line directories199025
+Node: Printing199650
+Node: Print201281
+Node: Print Examples202618
+Node: Output Separators205402
+Node: OFMT207161
+Node: Printf208519
+Node: Basic Printf209425
+Node: Control Letters210962
+Node: Format Modifiers214774
+Node: Printf Examples220785
+Node: Redirection223500
+Node: Special Files230478
+Node: Special FD231011
+Ref: Special FD-Footnote-1234586
+Node: Special Network234660
+Node: Special Caveats235515
+Node: Close Files And Pipes236309
+Ref: Close Files And Pipes-Footnote-1243253
+Ref: Close Files And Pipes-Footnote-2243401
+Node: Expressions243551
+Node: Values244620
+Node: Constants245296
+Node: Scalar Constants245976
+Ref: Scalar Constants-Footnote-1246835
+Node: Nondecimal-numbers247017
+Node: Regexp Constants250076
+Node: Using Constant Regexps250551
+Node: Variables253556
+Node: Using Variables254211
+Node: Assignment Options255938
+Node: Conversion257819
+Ref: table-locale-affects263193
+Ref: Conversion-Footnote-1263817
+Node: All Operators263926
+Node: Arithmetic Ops264556
+Node: Concatenation267055
+Ref: Concatenation-Footnote-1269848
+Node: Assignment Ops269967
+Ref: table-assign-ops274955
+Node: Increment Ops276356
+Node: Truth Values and Conditions279834
+Node: Truth Values280917
+Node: Typing and Comparison281965
+Node: Variable Typing282754
+Ref: Variable Typing-Footnote-1286651
+Node: Comparison Operators286773
+Ref: table-relational-ops287183
+Node: POSIX String Comparison290732
+Ref: POSIX String Comparison-Footnote-1291689
+Node: Boolean Ops291827
+Ref: Boolean Ops-Footnote-1295905
+Node: Conditional Exp295996
+Node: Function Calls297728
+Node: Precedence301287
+Node: Patterns and Actions304940
+Node: Pattern Overview305994
+Node: Regexp Patterns307660
+Node: Expression Patterns308203
+Node: Ranges311777
+Node: BEGIN/END314743
+Node: Using BEGIN/END315493
+Ref: Using BEGIN/END-Footnote-1318224
+Node: I/O And BEGIN/END318338
+Node: Empty320607
+Node: BEGINFILE/ENDFILE320941
+Node: Using Shell Variables323766
+Node: Action Overview326045
+Node: Statements328402
+Node: If Statement330261
+Node: While Statement331760
+Node: Do Statement333804
+Node: For Statement334960
+Node: Switch Statement338112
+Node: Break Statement340209
+Node: Continue Statement342185
+Node: Next Statement343886
+Node: Nextfile Statement346268
+Node: Exit Statement348786
+Node: Built-in Variables351061
+Node: User-modified352156
+Ref: User-modified-Footnote-1360157
+Node: Auto-set360219
+Ref: Auto-set-Footnote-1369010
+Node: ARGC and ARGV369215
+Node: Arrays372974
+Node: Array Basics374545
+Node: Array Intro375256
+Node: Reference to Elements379574
+Node: Assigning Elements381844
+Node: Array Example382335
+Node: Scanning an Array384067
+Node: Delete386344
+Ref: Delete-Footnote-1388742
+Node: Numeric Array Subscripts388799
+Node: Uninitialized Subscripts390982
+Node: Multi-dimensional392610
+Node: Multi-scanning395701
+Node: Array Sorting397285
+Ref: Array Sorting-Footnote-1400483
+Node: Arrays of Arrays400677
+Node: Functions404785
+Node: Built-in405607
+Node: Calling Built-in406621
+Node: Numeric Functions408597
+Ref: Numeric Functions-Footnote-1412306
+Ref: Numeric Functions-Footnote-2412642
+Ref: Numeric Functions-Footnote-3412690
+Node: String Functions412959
+Ref: String Functions-Footnote-1434758
+Ref: String Functions-Footnote-2434887
+Ref: String Functions-Footnote-3435135
+Node: Gory Details435222
+Ref: table-sub-escapes436879
+Ref: table-posix-sub438193
+Ref: table-gensub-escapes439093
+Node: I/O Functions440264
+Ref: I/O Functions-Footnote-1446961
+Node: Time Functions447108
+Ref: Time Functions-Footnote-1457764
+Ref: Time Functions-Footnote-2457832
+Ref: Time Functions-Footnote-3457990
+Ref: Time Functions-Footnote-4458101
+Ref: Time Functions-Footnote-5458213
+Ref: Time Functions-Footnote-6458440
+Node: Bitwise Functions458706
+Ref: table-bitwise-ops459264
+Ref: Bitwise Functions-Footnote-1463424
+Node: I18N Functions463608
+Node: User-defined465238
+Node: Definition Syntax466042
+Ref: Definition Syntax-Footnote-1470672
+Node: Function Example470741
+Node: Function Caveats473335
+Node: Calling A Function473747
+Node: Variable Scope474836
+Node: Pass By Value/Reference476764
+Node: Return Statement480204
+Node: Dynamic Typing483146
+Node: Indirect Calls483883
+Node: Internationalization493568
+Node: I18N and L10N494994
+Node: Explaining gettext495678
+Ref: Explaining gettext-Footnote-1500738
+Ref: Explaining gettext-Footnote-2500921
+Node: Programmer i18n501086
+Node: Translator i18n505347
+Node: String Extraction506138
+Ref: String Extraction-Footnote-1507097
+Node: Printf Ordering507183
+Ref: Printf Ordering-Footnote-1509965
+Node: I18N Portability510029
+Ref: I18N Portability-Footnote-1512476
+Node: I18N Example512539
+Ref: I18N Example-Footnote-1515172
+Node: Gawk I18N515244
+Node: Advanced Features515811
+Node: Nondecimal Data517126
+Node: Two-way I/O518687
+Ref: Two-way I/O-Footnote-1524101
+Node: TCP/IP Networking524178
+Node: Profiling527031
+Node: Invoking Gawk534431
+Node: Command Line535738
+Node: Options536523
+Ref: Options-Footnote-1549611
+Node: Other Arguments549636
+Node: AWKPATH Variable552317
+Ref: AWKPATH Variable-Footnote-1555092
+Node: Exit Status555352
+Node: Include Files556024
+Node: Obsolete559625
+Node: Undocumented560426
+Node: Known Bugs560688
+Node: Library Functions561290
+Ref: Library Functions-Footnote-1564271
+Node: Library Names564442
+Ref: Library Names-Footnote-1567915
+Ref: Library Names-Footnote-2568134
+Node: General Functions568220
+Node: Nextfile Function569283
+Node: Strtonum Function573647
+Node: Assert Function576588
+Node: Round Function579892
+Node: Cliff Random Function581432
+Node: Ordinal Functions582447
+Ref: Ordinal Functions-Footnote-1585507
+Node: Join Function585723
+Ref: Join Function-Footnote-1587485
+Node: Gettimeofday Function587685
+Node: Data File Management591396
+Node: Filetrans Function592028
+Node: Rewind Function595454
+Node: File Checking596900
+Node: Empty Files597930
+Node: Ignoring Assigns600155
+Node: Getopt Function601703
+Ref: Getopt Function-Footnote-1612985
+Node: Passwd Functions613188
+Ref: Passwd Functions-Footnote-1622166
+Node: Group Functions622254
+Node: Sample Programs630351
+Node: Running Examples631020
+Node: Clones631748
+Node: Cut Program632880
+Node: Egrep Program642639
+Ref: Egrep Program-Footnote-1650389
+Node: Id Program650499
+Node: Split Program654106
+Node: Tee Program657574
+Node: Uniq Program660317
+Node: Wc Program667684
+Ref: Wc Program-Footnote-1671928
+Node: Miscellaneous Programs672124
+Node: Dupword Program673244
+Node: Alarm Program675275
+Node: Translate Program679817
+Ref: Translate Program-Footnote-1684196
+Ref: Translate Program-Footnote-2684433
+Node: Labels Program684567
+Ref: Labels Program-Footnote-1687858
+Node: Word Sorting687942
+Node: History Sorting692289
+Node: Extract Program694127
+Node: Simple Sed701485
+Node: Igawk Program704542
+Ref: Igawk Program-Footnote-1719273
+Ref: Igawk Program-Footnote-2719474
+Node: Signature Program719612
+Node: Debugger720692
+Node: Debugging721568
+Node: Debugging Concepts721882
+Node: Debugging Terms723735
+Node: Awk Debugging726283
+Node: Sample dgawk session727175
+Node: dgawk invocation727667
+Node: Finding The Bug728851
+Node: List of Debugger Commands735366
+Node: Breakpoint Control736681
+Node: Dgawk Execution Control739891
+Node: Viewing And Changing Data743240
+Node: Dgawk Stack746536
+Node: Dgawk Info747997
+Node: Miscellaneous Dgawk Commands751935
+Node: Readline Support757651
+Node: Dgawk Limitations758467
+Node: Language History760639
+Node: V7/SVR3.1762016
+Node: SVR4764311
+Node: POSIX765756
+Node: BTL767468
+Node: POSIX/GNU769158
+Node: Contributors778822
+Node: Installation782431
+Node: Gawk Distribution783402
+Node: Getting783886
+Node: Extracting784712
+Node: Distribution contents786100
+Node: Unix Installation791173
+Node: Quick Installation791764
+Node: Additional Configuration Options793466
+Node: Configuration Philosophy795229
+Node: Non-Unix Installation797593
+Node: PC Installation798058
+Node: PC Binary Installation799364
+Node: PC Compiling801207
+Node: PC Dynamic805712
+Node: PC Using808075
+Node: Cygwin812623
+Node: MSYS813607
+Node: VMS Installation814113
+Node: VMS Compilation814717
+Node: VMS Installation Details816294
+Node: VMS Running817924
+Node: VMS POSIX819521
+Node: VMS Old Gawk820819
+Node: Unsupported821288
+Node: Atari Installation821750
+Node: Atari Compiling823037
+Node: Atari Using824926
+Node: BeOS Installation827773
+Node: Tandem Installation828918
+Node: Bugs830597
+Node: Other Versions834429
+Node: Notes839651
+Node: Compatibility Mode840343
+Node: Additions841126
+Node: Adding Code841876
+Node: New Ports847928
+Node: Dynamic Extensions852060
+Node: Internals853441
+Node: Plugin License863846
+Node: Sample Library864480
+Node: Internal File Description865144
+Node: Internal File Ops868839
+Ref: Internal File Ops-Footnote-1873715
+Node: Using Internal File Ops873863
+Node: Future Extensions875888
+Node: Basic Concepts879925
+Node: Basic High Level880682
+Ref: Basic High Level-Footnote-1884801
+Node: Basic Data Typing884995
+Node: Floating Point Issues889432
+Node: String Conversion Precision890515
+Ref: String Conversion Precision-Footnote-1892209
+Node: Unexpected Results892318
+Node: POSIX Floating Point Problems894144
+Ref: POSIX Floating Point Problems-Footnote-1897843
+Node: Glossary897881
+Node: Copying921649
+Node: GNU Free Documentation License959206
+Node: next-edition984350
+Node: unresolved984702
+Node: revision985202
+Node: consistency985625
+Node: Index988978
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 75107215..42560264 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -504,6 +504,9 @@ particular records in a file and perform operations upon them.
 * Function Example::               An example function definition and what it
                                    does.
 * Function Caveats::               Things to watch out for.
+* Calling A Function::             Don't use blanks.
+* Variable Scope::                 Controlling variable scope.
+* Pass By Value/Reference::        Passing parameters.
 * Return Statement::               Specifying the value a function returns.
 * Dynamic Typing::                 How variable types can change at runtime.
 * Indirect Calls::                 Choosing the function to call at runtime.
@@ -12869,7 +12872,6 @@ The second half of this @value{CHAPTER} describes these
 @node Built-in
 @section Built-in Functions
 
-@c 2e: USE TEXINFO-2 FUNCTION DEFINITION STUFF!!!!!!!!!!!!!
 @dfn{Built-in} functions are always available for
 your @command{awk} program to call.  This @value{SECTION} defines all
 the built-in
@@ -15318,6 +15320,17 @@ function ctime(ts,    format)
 @subsection Calling User-Defined Functions
 
 @c STARTOFRANGE fudc
+This section describes how to call a user-defined function.
+
+@menu
+* Calling A Function::       Don't use blanks.
+* Variable Scope::           Controlling variable scope.
+* Pass By Value/Reference::  Passing parameters.
+@end menu
+
+@node Calling A Function
+@subsubsection Writing A Function Call
+
 @cindex functions, user-defined, calling
 @dfn{Calling a function} means causing the function to run and do its job.
 A function call is an expression and its value is the value returned by
@@ -15341,12 +15354,119 @@ to concatenate a variable with an expression in parentheses.  However, it
 notices that you used a function name and not a variable name, and reports
 an error.
 
+@node Variable Scope
+@subsubsection Controlling Variable Scope
+
+@cindex local variables
+@cindex variables, local
+There is no way to make a variable local to a @code{@{ @dots{} @}} block in
+@command{awk}, but you can make a variable local to a function. It is
+good practice to do so whenever a variable is needed only in that
+function.
+
+To make a variable local to a function, simply declare the variable as
+an argument after the actual function arguments
+(@pxref{Definition Syntax}).
+Look at the following example where variable
+@code{i} is a global variable used by both functions @code{foo()} and
+@code{bar()}:
+
+@example
+function bar()
+@{
+    for (i = 0; i < 3; i++)
+        print "bar's i=" i
+@}
+function foo(j)
+@{
+    i = j + 1
+    print "foo's i=" i
+    bar()
+    print "foo's i=" i
+@}
+
+BEGIN @{ 
+      i = 10
+      print "top's i=" i
+      foo(0)
+      print "top's i=" i
+@}
+@end example
+
+Running this script produces the following, because the @code{i} in
+functions @code{foo()} and @code{bar()} and at the top level refer to the same
+variable instance:
+
+@example
+top's i=10
+foo's i=1
+bar's i=0
+bar's i=1
+bar's i=2
+foo's i=3
+foo's i=3
+top's i=3
+@end example
+
+If you want @code{i} to be local to both @code{foo()} and @code{bar()} do as
+follows (the extra-space before @code{i} is a coding convention to
+indicate that @code{i} is a local variable, not an argument):
+
+@example
+function bar(    i)
+@{
+    for (i = 0; i < 3; i++) 
+        print "bar's i=" i
+@}
+function foo(j,    i)
+@{
+    i = j + 1
+    print "foo's i=" i
+    bar()
+    print "foo's i=" i
+@}
+
+BEGIN @{ 
+      i = 10
+      foo(0) 
+@}
+@end example
+
+Running the corrected script produces the following:
+
+@example
+top's i=10
+bar's i=1
+foo's i=0
+foo's i=1
+foo's i=2
+bar's i=1
+top's i=10
+@end example
+
+@node Pass By Value/Reference
+@subsubsection Passing Function Arguments By Value Or By Reference
+
+In @command{awk}, when you declare a function, there is no way to
+declare explicitly whether the arguments are passed @dfn{by value} or
+@dfn{by reference}.
+
+Instead the passing convention is determined at runtime when
+the function is called according to the following rule:
+
+@itemize
+@item
+If the argument is an array variable, then it is passed by reference,
+@item
+Otherwise the argument is passed by value.
+@end itemize
+
 @cindex call by value
-When a function is called, it is given a @emph{copy} of the values of
-its arguments.  This is known as @dfn{call by value}.  The caller may use
-a variable as the expression for the argument, but the called function
-does not know this---it only knows what value the argument had.  For
-example, if you write the following code:
+Passing an argument by value means that when a function is called, it
+is given a @emph{copy} of the value of this argument.
+The caller may use a variable as the expression for the argument, but
+the called function does not know this---it only knows what value the
+argument had.  For example, if you write the following code:
 
 @example
 foo = "bar"
@@ -15364,9 +15484,9 @@ does this:
 @example
 function myfunc(str)
 @{
-  print str
-  str = "zzz"
-  print str
+   print str
+   str = "zzz"
+   print str
 @}
 @end example