Merge branch 'gawk-4.1-stable'

4 files changed, 817 insertions, 760 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index ae380bbd..681f3d86 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2014-08-24         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Continuing on reviewer comments.
+
 2014-08-23         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Continuing on reviewer comments.
diff --git a/doc/gawk.info b/doc/gawk.info
index 631a1fa0..73844d92 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -905,23 +905,19 @@ A Rose by Any Other Name
 
 The `awk' language has evolved over the years. Full details are
 provided in *note Language History::.  The language described in this
-Info file is often referred to as "new `awk'" (`nawk').
+Info file is often referred to as "new `awk'".  By analogy, the
+original version of `awk' is referred to as "old `awk'."
 
-   For some time after new `awk' was introduced, there were systems
-with multiple versions of `awk'.  Some systems had an `awk' utility
-that implemented the original version of the `awk' language and a
-`nawk' utility for the new version.  Others had an `oawk' version for
-the "old `awk'" language and plain `awk' for the new one.  Still others
-only had one version, which is usually the new one.
+   Today, on most systems, when you run the `awk' utility, you get some
+version of new `awk'.(1) If your system's standard `awk' is the old
+one, you will see something like this if you try the test program:
 
-   Today, only Solaris systems still use an old `awk' for the default
-`awk' utility. (A more modern `awk' lives in `/usr/xpg6/bin' on these
-systems.)  All other modern systems use some version of new `awk'.(1)
+     $ awk 1 /dev/null
+     error--> awk: syntax error near line 1
+     error--> awk: bailing out near line 1
 
-   It is likely that you already have some version of new `awk' on your
-system, which is what you should use when running your programs.  (Of
-course, if you're reading this Info file, chances are good that you
-have `gawk'!)
+In this case, you should find a version of new `awk', or just install
+`gawk'!
 
    Throughout this Info file, whenever we refer to a language feature
 that should be available in any complete implementation of POSIX `awk',
@@ -930,7 +926,9 @@ specific to the GNU implementation, we use the term `gawk'.
 
    ---------- Footnotes ----------
 
-   (1) Many of these systems use `gawk' for their `awk' implementation!
+   (1) Only Solaris systems still use an old `awk' for the default
+`awk' utility. A more modern `awk' lives in `/usr/xpg6/bin' on these
+systems.
 
 
 File: gawk.info,  Node: This Manual,  Next: Conventions,  Prev: Names,  Up: Preface
@@ -1548,8 +1546,8 @@ like this:
      BEGIN { print "Don't Panic!" }
 
 After making this file executable (with the `chmod' utility), simply
-type `advice' at the shell and the system arranges to run `awk'(2) as
-if you had typed `awk -f advice':
+type `advice' at the shell and the system arranges to run `awk' as if
+you had typed `awk -f advice':
 
      $ chmod +x advice
      $ advice
@@ -1563,7 +1561,24 @@ at the shell.)
 program that users can invoke without their having to know that the
 program is written in `awk'.
 
-                     Portability Issues with `#!'
+                          Understanding `#!'
+
+   `awk' is an "interpreted" language. This means that the `awk'
+utility reads your program and then processes your data according to
+the instructions in your program. (This is different from a "compiled"
+language such as C, where your program is first compiled into machine
+code that is executed directly by your system's hardware.)  The `awk'
+utility is thus termed an "interpreter".  Many modern languages are
+interperted.
+
+   The line beginning with `#!' lists the full file name of an
+interpreter to run and a single optional initial command-line argument
+to pass to that interpreter.  The operating system then runs the
+interpreter with the given argument and the full argument list of the
+executed program.  The first argument in the list is the full file name
+of the `awk' program.  The rest of the argument list contains either
+options to `awk', or data files, or both. Note that on many systems
+`awk' may be found in `/usr/bin' instead of in `/bin'. Caveat Emptor.
 
    Some systems limit the length of the interpreter name to 32
 characters.  Often, this can be dealt with by using a symbolic link.
@@ -1585,15 +1600,6 @@ the name of your script (`advice').  (d.c.)  Don't rely on the value of
    (1) The `#!' mechanism works on GNU/Linux systems, BSD-based systems
 and commercial Unix systems.
 
-   (2) The line beginning with `#!' lists the full file name of an
-interpreter to run and a single optional initial command-line argument
-to pass to that interpreter.  The operating system then runs the
-interpreter with the given argument and the full argument list of the
-executed program.  The first argument in the list is the full file name
-of the `awk' program.  The rest of the argument list contains either
-options to `awk', or data files, or both. Note that on many systems
-`awk' may be found in `/usr/bin' instead of in `/bin'. Caveat Emptor.
-
 
 File: gawk.info,  Node: Comments,  Next: Quoting,  Prev: Executable Scripts,  Up: Running gawk
 
@@ -1838,7 +1844,8 @@ shipments during the year.  Each record contains the month, the number
 of green crates shipped, the number of red boxes shipped, the number of
 orange bags shipped, and the number of blue packages shipped,
 respectively.  There are 16 entries, covering the 12 months of last year
-and the first four months of the current year.
+and the first four months of the current year.  An empty line separates
+the data for the two years.
 
      Jan  13  25  15 115
      Feb  15  32  24 226
@@ -1918,11 +1925,6 @@ often more than one way to do things in `awk'.  At some point, you may
 want to look back at these examples and see if you can come up with
 different ways to do the same things shown here:
 
-   * Print the length of the longest input line:
-
-          awk '{ if (length($0) > max) max = length($0) }
-               END { print max }' data
-
    * Print every line that is longer than 80 characters:
 
           awk 'length($0) > 80' data
@@ -1930,15 +1932,20 @@ different ways to do the same things shown here:
      The sole rule has a relational expression as its pattern and it
      has no action--so it uses the default action, printing the record.
 
+   * Print the length of the longest input line:
+
+          awk '{ if (length($0) > max) max = length($0) }
+               END { print max }' data
+
    * Print the length of the longest line in `data':
 
           expand data | awk '{ if (x < length($0)) x = length($0) }
                         END { print "maximum line length is " x }'
 
-     This example differs slightly from the first example in this list:
-     The input is processed by the `expand' utility to change TABs into
-     spaces, so the widths compared are actually the right-margin
-     columns, as opposed to the number of input characters on each line.
+     This example differs slightly from the previous one: The input is
+     processed by the `expand' utility to change TABs into spaces, so
+     the widths compared are actually the right-margin columns, as
+     opposed to the number of input characters on each line.
 
    * Print every line that has at least one field:
 
@@ -3521,22 +3528,20 @@ sequences and that are not listed in the table stand for themselves:
      matches of one `p' followed by any number of `h's.  This also
      matches just `p' if no `h's are present.
 
-     The `*' repeats the _smallest_ possible preceding expression.
-     (Use parentheses if you want to repeat a larger expression.)  It
-     finds as many repetitions as possible.  For example, `awk
-     '/\(c[ad][ad]*r x\)/ { print }' sample' prints every record in
-     `sample' containing a string of the form `(car x)', `(cdr x)',
-     `(cadr x)', and so on.  Notice the escaping of the parentheses by
-     preceding them with backslashes.
+     There are two subtle points to understand about how `*' works.
+     First, the `*' applies only to the single preceding regular
+     expression component (e.g., in `ph*', it applies just to the `h').
+     To cause `*' to apply to a larger sub-expression, use parentheses:
+     `(ph)*' matches `ph', `phph', `phphph' and so on.
+
+     Second, `*' finds as many repetititons as possible. If the text to
+     be matched is `phhhhhhhhhhhhhhooey', `ph*' matches all of the `h's.
 
 `+'
      This symbol is similar to `*', except that the preceding
      expression must be matched at least once.  This means that `wh+y'
      would match `why' and `whhy', but not `wy', whereas `wh*y' would
-     match all three.  The following is a simpler way of writing the
-     last `*' example:
-
-          awk '/\(c[ad]+r x\)/ { print }' sample
+     match all three.
 
 `?'
      This symbol is similar to `*', except that the preceding
@@ -10721,7 +10726,8 @@ array element value:
      Index 0     Value 8
      Index 2     Value ""
 
-The pairs are shown in jumbled order because their order is irrelevant.
+The pairs are shown in jumbled order because their order is
+irrelevant.(1)
 
    One advantage of associative arrays is that new pairs can be added
 at any time.  For example, suppose a tenth element is added to the array
@@ -10750,9 +10756,10 @@ from English to French:
 Here we decided to translate the number one in both spelled-out and
 numeric form--thus illustrating that a single array can have both
 numbers and strings as indices.  (In fact, array subscripts are always
-strings; this is discussed in more detail in *note Numeric Array
-Subscripts::.)  Here, the number `1' isn't double-quoted, since `awk'
-automatically converts it to a string.
+strings.  There are some subtleties to how numbers work when used as
+array subscripts; this is discussed in more detail in *note Numeric
+Array Subscripts::.)  Here, the number `1' isn't double-quoted, since
+`awk' automatically converts it to a string.
 
    The value of `IGNORECASE' has no effect upon array subscripting.
 The identical string value used to store an array element must be used
@@ -10763,6 +10770,11 @@ starting at one.  (*Note String Functions::.)
    `awk''s arrays are efficient--the time to access an element is
 independent of the number of elements in the array.
 
+   ---------- Footnotes ----------
+
+   (1) The ordering will vary among `awk' implementations, which
+typically use hash tables to store array elements and values.
+
 
 File: gawk.info,  Node: Reference to Elements,  Next: Assigning Elements,  Prev: Array Intro,  Up: Array Basics
 
@@ -13258,7 +13270,10 @@ File: gawk.info,  Node: Definition Syntax,  Next: Function Example,  Up: User-de
 9.2.1 Function Definition Syntax
 --------------------------------
 
-Definitions of functions can appear anywhere between the rules of an
+     It's entirely fair to say that the `awk' syntax for local variable
+     definitions is appallingly awful -- Brian Kernighan
+
+   Definitions of functions can appear anywhere between the rules of an
 `awk' program.  Thus, the general form of an `awk' program is extended
 to include sequences of rules _and_ user-defined function definitions.
 There is no need to put the definition of a function before all uses of
@@ -13288,7 +13303,7 @@ have a parameter with the same name as the function itself.  In
 addition, according to the POSIX standard, function parameters cannot
 have the same name as one of the special built-in variables (*note
 Built-in Variables::).  Not all versions of `awk' enforce this
-restriction.)
+restriction.
 
    Local variables act like the empty string if referenced where a
 string value is required, and like zero if referenced where a numeric
@@ -31010,7 +31025,7 @@ Index
 * + (plus sign), ++ operator:            Increment Ops.       (line  11)
 * + (plus sign), += operator <1>:        Precedence.          (line  95)
 * + (plus sign), += operator:            Assignment Ops.      (line  82)
-* + (plus sign), regexp operator:        Regexp Operators.    (line 104)
+* + (plus sign), regexp operator:        Regexp Operators.    (line 105)
 * , (comma), in range patterns:          Ranges.              (line   6)
 * - (hyphen), - operator:                Precedence.          (line  52)
 * - (hyphen), -- operator <1>:           Precedence.          (line  46)
@@ -31153,7 +31168,7 @@ Index
 * ? (question mark), ?: operator:        Precedence.          (line  92)
 * ? (question mark), regexp operator <1>: GNU Regexp Operators.
                                                               (line  59)
-* ? (question mark), regexp operator:    Regexp Operators.    (line 113)
+* ? (question mark), regexp operator:    Regexp Operators.    (line 111)
 * [] (square brackets), regexp operator: Regexp Operators.    (line  56)
 * \ (backslash):                         Comments.            (line  50)
 * \ (backslash) in shell commands:       Read Terminal.       (line  25)
@@ -31275,7 +31290,7 @@ Index
 * ARGC/ARGV variables, command-line arguments: Other Arguments.
                                                               (line  12)
 * ARGC/ARGV variables, how to use:       ARGC and ARGV.       (line   6)
-* ARGC/ARGV variables, portability and:  Executable Scripts.  (line  42)
+* ARGC/ARGV variables, portability and:  Executable Scripts.  (line  59)
 * ARGIND variable:                       Auto-set.            (line  44)
 * ARGIND variable, command-line arguments: Other Arguments.   (line  12)
 * arguments, command-line <1>:           ARGC and ARGV.       (line   6)
@@ -31295,7 +31310,7 @@ Index
 * arrays:                                Arrays.              (line   6)
 * arrays of arrays:                      Arrays of Arrays.    (line   6)
 * arrays, an example of using:           Array Example.       (line   6)
-* arrays, and IGNORECASE variable:       Array Intro.         (line  92)
+* arrays, and IGNORECASE variable:       Array Intro.         (line  94)
 * arrays, as parameters to functions:    Pass By Value/Reference.
                                                               (line  47)
 * arrays, associative:                   Array Intro.         (line  50)
@@ -31323,7 +31338,7 @@ Index
                                                               (line   6)
 * arrays, sorting, and IGNORECASE variable: Array Sorting Functions.
                                                               (line  83)
-* arrays, sparse:                        Array Intro.         (line  71)
+* arrays, sparse:                        Array Intro.         (line  72)
 * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts.
                                                               (line   6)
 * arrays, unassigned elements:           Reference to Elements.
@@ -31410,8 +31425,7 @@ Index
 * awk, uses for <1>:                     When.                (line   6)
 * awk, uses for <2>:                     Getting Started.     (line  12)
 * awk, uses for:                         Preface.             (line  21)
-* awk, versions of <1>:                  V7/SVR3.1.           (line   6)
-* awk, versions of:                      Names.               (line  10)
+* awk, versions of:                      V7/SVR3.1.           (line   6)
 * awk, versions of, changes between SVR3.1 and SVR4: SVR4.    (line   6)
 * awk, versions of, changes between SVR4 and POSIX awk: POSIX.
                                                               (line   6)
@@ -31620,7 +31634,7 @@ Index
 * case keyword:                          Switch Statement.    (line   6)
 * case sensitivity, and regexps:         User-modified.       (line  76)
 * case sensitivity, and string comparisons: User-modified.    (line  76)
-* case sensitivity, array indices and:   Array Intro.         (line  92)
+* case sensitivity, array indices and:   Array Intro.         (line  94)
 * case sensitivity, converting case:     String Functions.    (line 520)
 * case sensitivity, example programs:    Library Functions.   (line  53)
 * case sensitivity, gawk:                Case-sensitivity.    (line  26)
@@ -31699,7 +31713,7 @@ Index
 * common extensions, \x escape sequence: Escape Sequences.    (line  61)
 * common extensions, BINMODE variable:   PC Using.            (line  33)
 * common extensions, delete to delete entire arrays: Delete.  (line  39)
-* common extensions, func keyword:       Definition Syntax.   (line  89)
+* common extensions, func keyword:       Definition Syntax.   (line  92)
 * common extensions, length() applied to an array: String Functions.
                                                               (line 197)
 * common extensions, RS as a regexp:     gawk split records.  (line   6)
@@ -32219,7 +32233,7 @@ Index
 * extensions, common, BINMODE variable:  PC Using.            (line  33)
 * extensions, common, delete to delete entire arrays: Delete. (line  39)
 * extensions, common, fflush() function: I/O Functions.       (line  43)
-* extensions, common, func keyword:      Definition Syntax.   (line  89)
+* extensions, common, func keyword:      Definition Syntax.   (line  92)
 * extensions, common, length() applied to an array: String Functions.
                                                               (line 197)
 * extensions, common, RS as a regexp:    gawk split records.  (line   6)
@@ -32409,7 +32423,7 @@ Index
 * functions, built-in <1>:               Functions.           (line   6)
 * functions, built-in:                   Function Calls.      (line  10)
 * functions, built-in, evaluation order: Calling Built-in.    (line  30)
-* functions, defining:                   Definition Syntax.   (line   6)
+* functions, defining:                   Definition Syntax.   (line   9)
 * functions, library:                    Library Functions.   (line   6)
 * functions, library, assertions:        Assert Function.     (line   6)
 * functions, library, associative arrays and: Library Names.  (line  57)
@@ -32432,9 +32446,9 @@ Index
 * functions, library, rounding numbers:  Round Function.      (line   6)
 * functions, library, user database, reading: Passwd Functions.
                                                               (line   6)
-* functions, names of <1>:               Definition Syntax.   (line  20)
+* functions, names of <1>:               Definition Syntax.   (line  23)
 * functions, names of:                   Arrays.              (line  18)
-* functions, recursive:                  Definition Syntax.   (line  79)
+* functions, recursive:                  Definition Syntax.   (line  82)
 * functions, string-translation:         I18N Functions.      (line   6)
 * functions, undefined:                  Pass By Value/Reference.
                                                               (line  71)
@@ -32493,7 +32507,7 @@ Index
 * gawk, IGNORECASE variable in <1>:      Array Sorting Functions.
                                                               (line  83)
 * gawk, IGNORECASE variable in <2>:      String Functions.    (line  58)
-* gawk, IGNORECASE variable in <3>:      Array Intro.         (line  92)
+* gawk, IGNORECASE variable in <3>:      Array Intro.         (line  94)
 * gawk, IGNORECASE variable in <4>:      User-modified.       (line  76)
 * gawk, IGNORECASE variable in:          Case-sensitivity.    (line  26)
 * gawk, implementation issues:           Notes.               (line   6)
@@ -32507,7 +32521,7 @@ Index
                                                               (line  13)
 * gawk, interpreter, adding code to:     Using Internal File Ops.
                                                               (line   6)
-* gawk, interval expressions and:        Regexp Operators.    (line 141)
+* gawk, interval expressions and:        Regexp Operators.    (line 139)
 * gawk, line continuation in:            Conditional Exp.     (line  34)
 * gawk, LINT variable in:                User-modified.       (line  88)
 * gawk, list of contributors to:         Contributors.        (line   6)
@@ -32525,7 +32539,7 @@ Index
                                                               (line  26)
 * gawk, regular expressions, operators:  GNU Regexp Operators.
                                                               (line   6)
-* gawk, regular expressions, precedence: Regexp Operators.    (line 163)
+* gawk, regular expressions, precedence: Regexp Operators.    (line 161)
 * gawk, RT variable in <1>:              Auto-set.            (line 265)
 * gawk, RT variable in <2>:              Multiple Line.       (line 129)
 * gawk, RT variable in:                  awk split records.   (line 124)
@@ -32659,7 +32673,7 @@ Index
 * ignore breakpoint:                     Breakpoint Control.  (line  87)
 * ignore debugger command:               Breakpoint Control.  (line  87)
 * IGNORECASE variable:                   User-modified.       (line  76)
-* IGNORECASE variable, and array indices: Array Intro.        (line  92)
+* IGNORECASE variable, and array indices: Array Intro.        (line  94)
 * IGNORECASE variable, and array sorting functions: Array Sorting Functions.
                                                               (line  83)
 * IGNORECASE variable, in example programs: Library Functions.
@@ -32744,7 +32758,7 @@ Index
 * internationalizing a program:          Explaining gettext.  (line   6)
 * interpreted programs <1>:              Glossary.            (line 356)
 * interpreted programs:                  Basic High Level.    (line  15)
-* interval expressions, regexp operator: Regexp Operators.    (line 118)
+* interval expressions, regexp operator: Regexp Operators.    (line 116)
 * inventory-shipped file:                Sample Data Files.   (line  32)
 * invoke shell command:                  I/O Functions.       (line  75)
 * isarray:                               Type Functions.      (line  11)
@@ -32936,11 +32950,10 @@ Index
 * names, arrays/variables <1>:           Library Names.       (line   6)
 * names, arrays/variables:               Arrays.              (line  18)
 * names, functions <1>:                  Library Names.       (line   6)
-* names, functions:                      Definition Syntax.   (line  20)
+* names, functions:                      Definition Syntax.   (line  23)
 * namespace issues <1>:                  Library Names.       (line   6)
 * namespace issues:                      Arrays.              (line  18)
-* namespace issues, functions:           Definition Syntax.   (line  20)
-* nawk utility:                          Names.               (line  10)
+* namespace issues, functions:           Definition Syntax.   (line  23)
 * NetBSD:                                Glossary.            (line 611)
 * networks, programming:                 TCP/IP Networking.   (line   6)
 * networks, support for:                 Special Network.     (line   6)
@@ -33019,7 +33032,6 @@ Index
 * numeric, output format:                OFMT.                (line   6)
 * numeric, strings:                      Variable Typing.     (line   6)
 * o debugger command (alias for option): Debugger Info.       (line  57)
-* oawk utility:                          Names.               (line  10)
 * obsolete features:                     Obsolete.            (line   6)
 * octal numbers:                         Nondecimal-numbers.  (line   6)
 * octal values, enabling interpretation of: Options.          (line 211)
@@ -33140,13 +33152,13 @@ Index
 * plus sign (+), ++ operator:            Increment Ops.       (line  11)
 * plus sign (+), += operator <1>:        Precedence.          (line  95)
 * plus sign (+), += operator:            Assignment Ops.      (line  82)
-* plus sign (+), regexp operator:        Regexp Operators.    (line 104)
+* plus sign (+), regexp operator:        Regexp Operators.    (line 105)
 * pointers to functions:                 Indirect Calls.      (line   6)
 * portability:                           Escape Sequences.    (line 100)
 * portability, #! (executable scripts):  Executable Scripts.  (line  33)
 * portability, ** operator and:          Arithmetic Ops.      (line  81)
 * portability, **= operator and:         Assignment Ops.      (line 143)
-* portability, ARGV variable:            Executable Scripts.  (line  42)
+* portability, ARGV variable:            Executable Scripts.  (line  59)
 * portability, backslash continuation and: Statements/Lines.  (line  30)
 * portability, backslash in escape sequences: Escape Sequences.
                                                               (line 118)
@@ -33156,7 +33168,7 @@ Index
                                                               (line  65)
 * portability, deleting array elements:  Delete.              (line  56)
 * portability, example programs:         Library Functions.   (line  42)
-* portability, functions, defining:      Definition Syntax.   (line 105)
+* portability, functions, defining:      Definition Syntax.   (line 108)
 * portability, gawk:                     New Ports.           (line   6)
 * portability, gettext library and:      Explaining gettext.  (line  11)
 * portability, internationalization and: I18N Portability.    (line   6)
@@ -33202,18 +33214,18 @@ Index
                                                               (line  40)
 * POSIX awk, field separators and:       Fields.              (line   6)
 * POSIX awk, FS variable and:            User-modified.       (line  60)
-* POSIX awk, function keyword in:        Definition Syntax.   (line  89)
+* POSIX awk, function keyword in:        Definition Syntax.   (line  92)
 * POSIX awk, functions and, gsub()/sub(): Gory Details.       (line  90)
 * POSIX awk, functions and, length():    String Functions.    (line 176)
 * POSIX awk, GNU long options and:       Options.             (line  15)
-* POSIX awk, interval expressions in:    Regexp Operators.    (line 137)
+* POSIX awk, interval expressions in:    Regexp Operators.    (line 135)
 * POSIX awk, next/nextfile statements and: Next Statement.    (line  45)
 * POSIX awk, numeric strings and:        Variable Typing.     (line   6)
 * POSIX awk, OFMT variable and <1>:      Strings And Numbers. (line  57)
 * POSIX awk, OFMT variable and:          OFMT.                (line  27)
 * POSIX awk, period (.), using:          Regexp Operators.    (line  51)
 * POSIX awk, printf format strings and:  Format Modifiers.    (line 159)
-* POSIX awk, regular expressions and:    Regexp Operators.    (line 163)
+* POSIX awk, regular expressions and:    Regexp Operators.    (line 161)
 * POSIX awk, timestamps and:             Time Functions.      (line   6)
 * POSIX awk, | I/O operator and:         Getline/Pipe.        (line  55)
 * POSIX mode:                            Options.             (line 252)
@@ -33224,7 +33236,7 @@ Index
 * PREC variable:                         User-modified.       (line 124)
 * precedence <1>:                        Precedence.          (line   6)
 * precedence:                            Increment Ops.       (line  60)
-* precedence, regexp operators:          Regexp Operators.    (line 158)
+* precedence, regexp operators:          Regexp Operators.    (line 156)
 * print debugger command:                Viewing And Changing Data.
                                                               (line  36)
 * print statement:                       Printing.            (line  16)
@@ -33291,7 +33303,7 @@ Index
 * programming conventions, functions, calling: Calling Built-in.
                                                               (line  10)
 * programming conventions, functions, writing: Definition Syntax.
-                                                              (line  61)
+                                                              (line  64)
 * programming conventions, gawk extensions: Internal File Ops.
                                                               (line  45)
 * programming conventions, private variable names: Library Names.
@@ -33311,7 +33323,7 @@ Index
 * question mark (?), ?: operator:        Precedence.          (line  92)
 * question mark (?), regexp operator <1>: GNU Regexp Operators.
                                                               (line  59)
-* question mark (?), regexp operator:    Regexp Operators.    (line 113)
+* question mark (?), regexp operator:    Regexp Operators.    (line 111)
 * QuikTrim Awk:                          Other Versions.      (line 135)
 * quit debugger command:                 Miscellaneous Debugger Commands.
                                                               (line  99)
@@ -33361,7 +33373,7 @@ Index
 * records, splitting input into:         Records.             (line   6)
 * records, terminating:                  awk split records.   (line 124)
 * records, treating files as:            gawk split records.  (line  92)
-* recursive functions:                   Definition Syntax.   (line  79)
+* recursive functions:                   Definition Syntax.   (line  82)
 * redirect gawk output, in debugger:     Debugger Info.       (line  72)
 * redirection of input:                  Getline/File.        (line   6)
 * redirection of output:                 Redirection.         (line   6)
@@ -33411,7 +33423,7 @@ Index
 * regular expressions, operators, gawk:  GNU Regexp Operators.
                                                               (line   6)
 * regular expressions, operators, precedence of: Regexp Operators.
-                                                              (line 158)
+                                                              (line 156)
 * regular expressions, searching for:    Egrep Program.       (line   6)
 * relational operators, See comparison operators: Typing and Comparison.
                                                               (line   9)
@@ -33531,7 +33543,7 @@ Index
 * set directory of message catalogs:     I18N Functions.      (line  12)
 * set watchpoint:                        Viewing And Changing Data.
                                                               (line  67)
-* shadowing of variable values:          Definition Syntax.   (line  67)
+* shadowing of variable values:          Definition Syntax.   (line  70)
 * shell quoting, double quote:           Read Terminal.       (line  25)
 * shell quoting, rules for:              Quoting.             (line   6)
 * shells, piping commands into:          Redirection.         (line 142)
@@ -33584,7 +33596,6 @@ Index
 * sidebar, Matching the Null String:     Gory Details.        (line 141)
 * sidebar, Operator Evaluation Order:    Increment Ops.       (line  58)
 * sidebar, Piping into sh:               Redirection.         (line 140)
-* sidebar, Portability Issues with #!:   Executable Scripts.  (line  31)
 * sidebar, Pre-POSIX awk Used OFMT For String Conversion: Strings And Numbers.
                                                               (line  55)
 * sidebar, Recipe For A Programming Language: History.        (line   6)
@@ -33593,6 +33604,7 @@ Index
                                                               (line  83)
 * sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops.
                                                               (line 146)
+* sidebar, Understanding #!:             Executable Scripts.  (line  31)
 * sidebar, Understanding $0:             Changing Fields.     (line 134)
 * sidebar, Using \n in Bracket Expressions of Dynamic Regexps: Computed Regexps.
                                                               (line  57)
@@ -33648,7 +33660,7 @@ Index
 * source code, QuikTrim Awk:             Other Versions.      (line 135)
 * source code, Solaris awk:              Other Versions.      (line  96)
 * source files, search path for:         Programs Exercises.  (line  63)
-* sparse arrays:                         Array Intro.         (line  71)
+* sparse arrays:                         Array Intro.         (line  72)
 * Spencer, Henry:                        Glossary.            (line  11)
 * split:                                 String Functions.    (line 313)
 * split string into array:               String Functions.    (line 294)
@@ -33908,7 +33920,7 @@ Index
 * variables, names of:                   Arrays.              (line  18)
 * variables, private:                    Library Names.       (line  11)
 * variables, setting:                    Options.             (line  32)
-* variables, shadowing:                  Definition Syntax.   (line  67)
+* variables, shadowing:                  Definition Syntax.   (line  70)
 * variables, types of:                   Assignment Ops.      (line  40)
 * variables, types of, comparison expressions and: Typing and Comparison.
                                                               (line   9)
@@ -34011,546 +34023,546 @@ Ref: Preface-Footnote-149226
 Ref: Preface-Footnote-249333
 Node: History49565
 Node: Names51939
-Ref: Names-Footnote-153403
-Node: This Manual53476
-Ref: This Manual-Footnote-159255
-Node: Conventions59355
-Node: Manual History61700
-Ref: Manual History-Footnote-164776
-Ref: Manual History-Footnote-264817
-Node: How To Contribute64891
-Node: Acknowledgments66130
-Node: Getting Started70878
-Node: Running gawk73312
-Node: One-shot74502
-Node: Read Terminal75727
-Ref: Read Terminal-Footnote-177690
-Node: Long77861
-Node: Executable Scripts79255
-Ref: Executable Scripts-Footnote-181088
-Ref: Executable Scripts-Footnote-281190
-Node: Comments81743
-Node: Quoting84216
-Node: DOS Quoting89529
-Node: Sample Data Files90204
-Node: Very Simple92758
-Node: Two Rules97531
-Node: More Complex99425
-Ref: More Complex-Footnote-1102357
-Node: Statements/Lines102442
-Ref: Statements/Lines-Footnote-1106898
-Node: Other Features107163
-Node: When108091
-Ref: When-Footnote-1109847
-Node: Intro Summary109912
-Node: Invoking Gawk110795
-Node: Command Line112310
-Node: Options113101
-Ref: Options-Footnote-1128748
-Node: Other Arguments128773
-Node: Naming Standard Input131435
-Node: Environment Variables132528
-Node: AWKPATH Variable133086
-Ref: AWKPATH Variable-Footnote-1135952
-Ref: AWKPATH Variable-Footnote-2135997
-Node: AWKLIBPATH Variable136257
-Node: Other Environment Variables137016
-Node: Exit Status140468
-Node: Include Files141143
-Node: Loading Shared Libraries144721
-Node: Obsolete146105
-Node: Undocumented146802
-Node: Invoking Summary147069
-Node: Regexp148669
-Node: Regexp Usage150128
-Node: Escape Sequences152161
-Node: Regexp Operators158061
-Ref: Regexp Operators-Footnote-1165579
-Ref: Regexp Operators-Footnote-2165726
-Node: Bracket Expressions165824
-Ref: table-char-classes167846
-Node: GNU Regexp Operators170786
-Node: Case-sensitivity174495
-Ref: Case-sensitivity-Footnote-1177387
-Ref: Case-sensitivity-Footnote-2177622
-Node: Leftmost Longest177730
-Node: Computed Regexps178931
-Node: Regexp Summary182303
-Node: Reading Files183772
-Node: Records185864
-Node: awk split records186586
-Node: gawk split records191444
-Ref: gawk split records-Footnote-1195965
-Node: Fields196002
-Ref: Fields-Footnote-1198966
-Node: Nonconstant Fields199052
-Ref: Nonconstant Fields-Footnote-1201282
-Node: Changing Fields201484
-Node: Field Separators207438
-Node: Default Field Splitting210140
-Node: Regexp Field Splitting211257
-Node: Single Character Fields214584
-Node: Command Line Field Separator215643
-Node: Full Line Fields219069
-Ref: Full Line Fields-Footnote-1219577
-Node: Field Splitting Summary219623
-Ref: Field Splitting Summary-Footnote-1222755
-Node: Constant Size222856
-Node: Splitting By Content227462
-Ref: Splitting By Content-Footnote-1231535
-Node: Multiple Line231575
-Ref: Multiple Line-Footnote-1237431
-Node: Getline237610
-Node: Plain Getline239821
-Node: Getline/Variable241916
-Node: Getline/File243063
-Node: Getline/Variable/File244447
-Ref: Getline/Variable/File-Footnote-1246046
-Node: Getline/Pipe246133
-Node: Getline/Variable/Pipe248819
-Node: Getline/Coprocess249926
-Node: Getline/Variable/Coprocess251178
-Node: Getline Notes251915
-Node: Getline Summary254719
-Ref: table-getline-variants255127
-Node: Read Timeout256039
-Ref: Read Timeout-Footnote-1259866
-Node: Command-line directories259924
-Node: Input Summary260828
-Node: Input Exercises263965
-Node: Printing264698
-Node: Print266420
-Node: Print Examples267913
-Node: Output Separators270692
-Node: OFMT272708
-Node: Printf274066
-Node: Basic Printf274972
-Node: Control Letters276511
-Node: Format Modifiers280502
-Node: Printf Examples286529
-Node: Redirection288993
-Node: Special Files295965
-Node: Special FD296498
-Ref: Special FD-Footnote-1300095
-Node: Special Network300169
-Node: Special Caveats301019
-Node: Close Files And Pipes301815
-Ref: Close Files And Pipes-Footnote-1308976
-Ref: Close Files And Pipes-Footnote-2309124
-Node: Output Summary309274
-Node: Output exercises310271
-Node: Expressions310951
-Node: Values312136
-Node: Constants312812
-Node: Scalar Constants313492
-Ref: Scalar Constants-Footnote-1314351
-Node: Nondecimal-numbers314601
-Node: Regexp Constants317601
-Node: Using Constant Regexps318076
-Node: Variables321148
-Node: Using Variables321803
-Node: Assignment Options323527
-Node: Conversion325402
-Node: Strings And Numbers325926
-Ref: Strings And Numbers-Footnote-1328988
-Node: Locale influences conversions329097
-Ref: table-locale-affects331814
-Node: All Operators332402
-Node: Arithmetic Ops333032
-Node: Concatenation335537
-Ref: Concatenation-Footnote-1338356
-Node: Assignment Ops338462
-Ref: table-assign-ops343445
-Node: Increment Ops344748
-Node: Truth Values and Conditions348186
-Node: Truth Values349269
-Node: Typing and Comparison350318
-Node: Variable Typing351111
-Node: Comparison Operators354763
-Ref: table-relational-ops355173
-Node: POSIX String Comparison358723
-Ref: POSIX String Comparison-Footnote-1359807
-Node: Boolean Ops359945
-Ref: Boolean Ops-Footnote-1364020
-Node: Conditional Exp364111
-Node: Function Calls365838
-Node: Precedence369718
-Node: Locales373387
-Node: Expressions Summary375018
-Node: Patterns and Actions377559
-Node: Pattern Overview378675
-Node: Regexp Patterns380352
-Node: Expression Patterns380895
-Node: Ranges384675
-Node: BEGIN/END387781
-Node: Using BEGIN/END388543
-Ref: Using BEGIN/END-Footnote-1391279
-Node: I/O And BEGIN/END391385
-Node: BEGINFILE/ENDFILE393656
-Node: Empty396587
-Node: Using Shell Variables396904
-Node: Action Overview399187
-Node: Statements401514
-Node: If Statement403362
-Node: While Statement404860
-Node: Do Statement406904
-Node: For Statement408060
-Node: Switch Statement411212
-Node: Break Statement413600
-Node: Continue Statement415641
-Node: Next Statement417466
-Node: Nextfile Statement419856
-Node: Exit Statement422492
-Node: Built-in Variables424896
-Node: User-modified426023
-Ref: User-modified-Footnote-1433712
-Node: Auto-set433774
-Ref: Auto-set-Footnote-1446693
-Ref: Auto-set-Footnote-2446898
-Node: ARGC and ARGV446954
-Node: Pattern Action Summary450858
-Node: Arrays453081
-Node: Array Basics454630
-Node: Array Intro455456
-Ref: figure-array-elements457429
-Node: Reference to Elements459836
-Node: Assigning Elements462286
-Node: Array Example462777
-Node: Scanning an Array464509
-Node: Controlling Scanning467510
-Ref: Controlling Scanning-Footnote-1472683
-Node: Delete472999
-Ref: Delete-Footnote-1475750
-Node: Numeric Array Subscripts475807
-Node: Uninitialized Subscripts477990
-Node: Multidimensional479615
-Node: Multiscanning482728
-Node: Arrays of Arrays484317
-Node: Arrays Summary488980
-Node: Functions491085
-Node: Built-in491958
-Node: Calling Built-in493036
-Node: Numeric Functions495024
-Ref: Numeric Functions-Footnote-1499860
-Ref: Numeric Functions-Footnote-2500217
-Ref: Numeric Functions-Footnote-3500265
-Node: String Functions500534
-Ref: String Functions-Footnote-1523531
-Ref: String Functions-Footnote-2523660
-Ref: String Functions-Footnote-3523908
-Node: Gory Details523995
-Ref: table-sub-escapes525768
-Ref: table-sub-proposed527288
-Ref: table-posix-sub528652
-Ref: table-gensub-escapes530192
-Ref: Gory Details-Footnote-1531368
-Node: I/O Functions531519
-Ref: I/O Functions-Footnote-1538629
-Node: Time Functions538776
-Ref: Time Functions-Footnote-1549240
-Ref: Time Functions-Footnote-2549308
-Ref: Time Functions-Footnote-3549466
-Ref: Time Functions-Footnote-4549577
-Ref: Time Functions-Footnote-5549689
-Ref: Time Functions-Footnote-6549916
-Node: Bitwise Functions550182
-Ref: table-bitwise-ops550744
-Ref: Bitwise Functions-Footnote-1554989
-Node: Type Functions555173
-Node: I18N Functions556315
-Node: User-defined557960
-Node: Definition Syntax558764
-Ref: Definition Syntax-Footnote-1563943
-Node: Function Example564012
-Ref: Function Example-Footnote-1566652
-Node: Function Caveats566674
-Node: Calling A Function567192
-Node: Variable Scope568147
-Node: Pass By Value/Reference571135
-Node: Return Statement574645
-Node: Dynamic Typing577629
-Node: Indirect Calls578558
-Node: Functions Summary588271
-Node: Library Functions590810
-Ref: Library Functions-Footnote-1594428
-Ref: Library Functions-Footnote-2594571
-Node: Library Names594742
-Ref: Library Names-Footnote-1598215
-Ref: Library Names-Footnote-2598435
-Node: General Functions598521
-Node: Strtonum Function599549
-Node: Assert Function602329
-Node: Round Function605655
-Node: Cliff Random Function607196
-Node: Ordinal Functions608212
-Ref: Ordinal Functions-Footnote-1611277
-Ref: Ordinal Functions-Footnote-2611529
-Node: Join Function611740
-Ref: Join Function-Footnote-1613511
-Node: Getlocaltime Function613711
-Node: Readfile Function617447
-Node: Data File Management619286
-Node: Filetrans Function619918
-Node: Rewind Function623987
-Node: File Checking625545
-Ref: File Checking-Footnote-1626677
-Node: Empty Files626878
-Node: Ignoring Assigns628857
-Node: Getopt Function630411
-Ref: Getopt Function-Footnote-1641714
-Node: Passwd Functions641917
-Ref: Passwd Functions-Footnote-1650896
-Node: Group Functions650984
-Ref: Group Functions-Footnote-1658915
-Node: Walking Arrays659128
-Node: Library Functions Summary660731
-Node: Library exercises662119
-Node: Sample Programs663399
-Node: Running Examples664169
-Node: Clones664897
-Node: Cut Program666121
-Node: Egrep Program675979
-Ref: Egrep Program-Footnote-1683566
-Node: Id Program683676
-Node: Split Program687330
-Ref: Split Program-Footnote-1690868
-Node: Tee Program690996
-Node: Uniq Program693783
-Node: Wc Program701204
-Ref: Wc Program-Footnote-1705469
-Node: Miscellaneous Programs705561
-Node: Dupword Program706774
-Node: Alarm Program708805
-Node: Translate Program713609
-Ref: Translate Program-Footnote-1718000
-Ref: Translate Program-Footnote-2718270
-Node: Labels Program718404
-Ref: Labels Program-Footnote-1721765
-Node: Word Sorting721849
-Node: History Sorting725892
-Node: Extract Program727728
-Node: Simple Sed735264
-Node: Igawk Program738326
-Ref: Igawk Program-Footnote-1752630
-Ref: Igawk Program-Footnote-2752831
-Node: Anagram Program752969
-Node: Signature Program756037
-Node: Programs Summary757284
-Node: Programs Exercises758499
-Node: Advanced Features762150
-Node: Nondecimal Data764098
-Node: Array Sorting765675
-Node: Controlling Array Traversal766372
-Node: Array Sorting Functions774652
-Ref: Array Sorting Functions-Footnote-1778559
-Node: Two-way I/O778753
-Ref: Two-way I/O-Footnote-1783697
-Ref: Two-way I/O-Footnote-2783876
-Node: TCP/IP Networking783958
-Node: Profiling786803
-Node: Advanced Features Summary794354
-Node: Internationalization796218
-Node: I18N and L10N797698
-Node: Explaining gettext798384
-Ref: Explaining gettext-Footnote-1803410
-Ref: Explaining gettext-Footnote-2803594
-Node: Programmer i18n803759
-Ref: Programmer i18n-Footnote-1808553
-Node: Translator i18n808602
-Node: String Extraction809396
-Ref: String Extraction-Footnote-1810529
-Node: Printf Ordering810615
-Ref: Printf Ordering-Footnote-1813397
-Node: I18N Portability813461
-Ref: I18N Portability-Footnote-1815910
-Node: I18N Example815973
-Ref: I18N Example-Footnote-1818679
-Node: Gawk I18N818751
-Node: I18N Summary819389
-Node: Debugger820728
-Node: Debugging821750
-Node: Debugging Concepts822191
-Node: Debugging Terms824047
-Node: Awk Debugging826644
-Node: Sample Debugging Session827536
-Node: Debugger Invocation828056
-Node: Finding The Bug829389
-Node: List of Debugger Commands835871
-Node: Breakpoint Control837203
-Node: Debugger Execution Control840867
-Node: Viewing And Changing Data844227
-Node: Execution Stack847585
-Node: Debugger Info849098
-Node: Miscellaneous Debugger Commands853092
-Node: Readline Support858276
-Node: Limitations859168
-Node: Debugging Summary861442
-Node: Arbitrary Precision Arithmetic862610
-Node: Computer Arithmetic864097
-Ref: Computer Arithmetic-Footnote-1868484
-Node: Math Definitions868541
-Ref: table-ieee-formats871830
-Ref: Math Definitions-Footnote-1872370
-Node: MPFR features872473
-Node: FP Math Caution874090
-Ref: FP Math Caution-Footnote-1875140
-Node: Inexactness of computations875509
-Node: Inexact representation876457
-Node: Comparing FP Values877812
-Node: Errors accumulate878776
-Node: Getting Accuracy880209
-Node: Try To Round882868
-Node: Setting precision883767
-Ref: table-predefined-precision-strings884449
-Node: Setting the rounding mode886242
-Ref: table-gawk-rounding-modes886606
-Ref: Setting the rounding mode-Footnote-1890060
-Node: Arbitrary Precision Integers890239
-Ref: Arbitrary Precision Integers-Footnote-1894012
-Node: POSIX Floating Point Problems894161
-Ref: POSIX Floating Point Problems-Footnote-1898037
-Node: Floating point summary898075
-Node: Dynamic Extensions900279
-Node: Extension Intro901831
-Node: Plugin License903096
-Node: Extension Mechanism Outline903781
-Ref: figure-load-extension904205
-Ref: figure-load-new-function905690
-Ref: figure-call-new-function906692
-Node: Extension API Description908676
-Node: Extension API Functions Introduction910126
-Node: General Data Types914993
-Ref: General Data Types-Footnote-1920686
-Node: Requesting Values920985
-Ref: table-value-types-returned921722
-Node: Memory Allocation Functions922680
-Ref: Memory Allocation Functions-Footnote-1925427
-Node: Constructor Functions925523
-Node: Registration Functions927281
-Node: Extension Functions927966
-Node: Exit Callback Functions930268
-Node: Extension Version String931516
-Node: Input Parsers932166
-Node: Output Wrappers941980
-Node: Two-way processors946496
-Node: Printing Messages948700
-Ref: Printing Messages-Footnote-1949777
-Node: Updating `ERRNO'949929
-Node: Accessing Parameters950668
-Node: Symbol Table Access951898
-Node: Symbol table by name952412
-Node: Symbol table by cookie954388
-Ref: Symbol table by cookie-Footnote-1958521
-Node: Cached values958584
-Ref: Cached values-Footnote-1962088
-Node: Array Manipulation962179
-Ref: Array Manipulation-Footnote-1963277
-Node: Array Data Types963316
-Ref: Array Data Types-Footnote-1966019
-Node: Array Functions966111
-Node: Flattening Arrays969985
-Node: Creating Arrays976837
-Node: Extension API Variables981568
-Node: Extension Versioning982204
-Node: Extension API Informational Variables984105
-Node: Extension API Boilerplate985191
-Node: Finding Extensions988995
-Node: Extension Example989555
-Node: Internal File Description990285
-Node: Internal File Ops994376
-Ref: Internal File Ops-Footnote-11005808
-Node: Using Internal File Ops1005948
-Ref: Using Internal File Ops-Footnote-11008295
-Node: Extension Samples1008563
-Node: Extension Sample File Functions1010087
-Node: Extension Sample Fnmatch1017655
-Node: Extension Sample Fork1019137
-Node: Extension Sample Inplace1020350
-Node: Extension Sample Ord1022025
-Node: Extension Sample Readdir1022861
-Ref: table-readdir-file-types1023717
-Node: Extension Sample Revout1024516
-Node: Extension Sample Rev2way1025107
-Node: Extension Sample Read write array1025848
-Node: Extension Sample Readfile1027727
-Node: Extension Sample API Tests1028827
-Node: Extension Sample Time1029352
-Node: gawkextlib1030667
-Node: Extension summary1033480
-Node: Extension Exercises1037173
-Node: Language History1037895
-Node: V7/SVR3.11039538
-Node: SVR41041858
-Node: POSIX1043300
-Node: BTL1044686
-Node: POSIX/GNU1045420
-Node: Feature History1051136
-Node: Common Extensions1064227
-Node: Ranges and Locales1065539
-Ref: Ranges and Locales-Footnote-11070156
-Ref: Ranges and Locales-Footnote-21070183
-Ref: Ranges and Locales-Footnote-31070417
-Node: Contributors1070638
-Node: History summary1076063
-Node: Installation1077432
-Node: Gawk Distribution1078383
-Node: Getting1078867
-Node: Extracting1079691
-Node: Distribution contents1081333
-Node: Unix Installation1087103
-Node: Quick Installation1087720
-Node: Additional Configuration Options1090162
-Node: Configuration Philosophy1091900
-Node: Non-Unix Installation1094251
-Node: PC Installation1094709
-Node: PC Binary Installation1096020
-Node: PC Compiling1097868
-Ref: PC Compiling-Footnote-11100867
-Node: PC Testing1100972
-Node: PC Using1102148
-Node: Cygwin1106300
-Node: MSYS1107109
-Node: VMS Installation1107623
-Node: VMS Compilation1108419
-Ref: VMS Compilation-Footnote-11109641
-Node: VMS Dynamic Extensions1109699
-Node: VMS Installation Details1111072
-Node: VMS Running1113324
-Node: VMS GNV1116158
-Node: VMS Old Gawk1116881
-Node: Bugs1117351
-Node: Other Versions1121355
-Node: Installation summary1127582
-Node: Notes1128638
-Node: Compatibility Mode1129503
-Node: Additions1130285
-Node: Accessing The Source1131210
-Node: Adding Code1132646
-Node: New Ports1138824
-Node: Derived Files1143305
-Ref: Derived Files-Footnote-11148386
-Ref: Derived Files-Footnote-21148420
-Ref: Derived Files-Footnote-31149016
-Node: Future Extensions1149130
-Node: Implementation Limitations1149736
-Node: Extension Design1150984
-Node: Old Extension Problems1152138
-Ref: Old Extension Problems-Footnote-11153655
-Node: Extension New Mechanism Goals1153712
-Ref: Extension New Mechanism Goals-Footnote-11157072
-Node: Extension Other Design Decisions1157261
-Node: Extension Future Growth1159367
-Node: Old Extension Mechanism1160203
-Node: Notes summary1161965
-Node: Basic Concepts1163151
-Node: Basic High Level1163832
-Ref: figure-general-flow1164104
-Ref: figure-process-flow1164703
-Ref: Basic High Level-Footnote-11167932
-Node: Basic Data Typing1168117
-Node: Glossary1171445
-Node: Copying1196597
-Node: GNU Free Documentation License1234153
-Node: Index1259289
+Ref: Names-Footnote-153033
+Node: This Manual53179
+Ref: This Manual-Footnote-158958
+Node: Conventions59058
+Node: Manual History61403
+Ref: Manual History-Footnote-164479
+Ref: Manual History-Footnote-264520
+Node: How To Contribute64594
+Node: Acknowledgments65833
+Node: Getting Started70581
+Node: Running gawk73015
+Node: One-shot74205
+Node: Read Terminal75430
+Ref: Read Terminal-Footnote-177393
+Node: Long77564
+Node: Executable Scripts78958
+Ref: Executable Scripts-Footnote-181759
+Node: Comments81861
+Node: Quoting84334
+Node: DOS Quoting89647
+Node: Sample Data Files90322
+Node: Very Simple92929
+Node: Two Rules97688
+Node: More Complex99582
+Ref: More Complex-Footnote-1102514
+Node: Statements/Lines102599
+Ref: Statements/Lines-Footnote-1107055
+Node: Other Features107320
+Node: When108248
+Ref: When-Footnote-1110004
+Node: Intro Summary110069
+Node: Invoking Gawk110952
+Node: Command Line112467
+Node: Options113258
+Ref: Options-Footnote-1128905
+Node: Other Arguments128930
+Node: Naming Standard Input131592
+Node: Environment Variables132685
+Node: AWKPATH Variable133243
+Ref: AWKPATH Variable-Footnote-1136109
+Ref: AWKPATH Variable-Footnote-2136154
+Node: AWKLIBPATH Variable136414
+Node: Other Environment Variables137173
+Node: Exit Status140625
+Node: Include Files141300
+Node: Loading Shared Libraries144878
+Node: Obsolete146262
+Node: Undocumented146959
+Node: Invoking Summary147226
+Node: Regexp148826
+Node: Regexp Usage150285
+Node: Escape Sequences152318
+Node: Regexp Operators158218
+Ref: Regexp Operators-Footnote-1165649
+Ref: Regexp Operators-Footnote-2165796
+Node: Bracket Expressions165894
+Ref: table-char-classes167916
+Node: GNU Regexp Operators170856
+Node: Case-sensitivity174565
+Ref: Case-sensitivity-Footnote-1177457
+Ref: Case-sensitivity-Footnote-2177692
+Node: Leftmost Longest177800
+Node: Computed Regexps179001
+Node: Regexp Summary182373
+Node: Reading Files183842
+Node: Records185934
+Node: awk split records186656
+Node: gawk split records191514
+Ref: gawk split records-Footnote-1196035
+Node: Fields196072
+Ref: Fields-Footnote-1199036
+Node: Nonconstant Fields199122
+Ref: Nonconstant Fields-Footnote-1201352
+Node: Changing Fields201554
+Node: Field Separators207508
+Node: Default Field Splitting210210
+Node: Regexp Field Splitting211327
+Node: Single Character Fields214654
+Node: Command Line Field Separator215713
+Node: Full Line Fields219139
+Ref: Full Line Fields-Footnote-1219647
+Node: Field Splitting Summary219693
+Ref: Field Splitting Summary-Footnote-1222825
+Node: Constant Size222926
+Node: Splitting By Content227532
+Ref: Splitting By Content-Footnote-1231605
+Node: Multiple Line231645
+Ref: Multiple Line-Footnote-1237501
+Node: Getline237680
+Node: Plain Getline239891
+Node: Getline/Variable241986
+Node: Getline/File243133
+Node: Getline/Variable/File244517
+Ref: Getline/Variable/File-Footnote-1246116
+Node: Getline/Pipe246203
+Node: Getline/Variable/Pipe248889
+Node: Getline/Coprocess249996
+Node: Getline/Variable/Coprocess251248
+Node: Getline Notes251985
+Node: Getline Summary254789
+Ref: table-getline-variants255197
+Node: Read Timeout256109
+Ref: Read Timeout-Footnote-1259936
+Node: Command-line directories259994
+Node: Input Summary260898
+Node: Input Exercises264035
+Node: Printing264768
+Node: Print266490
+Node: Print Examples267983
+Node: Output Separators270762
+Node: OFMT272778
+Node: Printf274136
+Node: Basic Printf275042
+Node: Control Letters276581
+Node: Format Modifiers280572
+Node: Printf Examples286599
+Node: Redirection289063
+Node: Special Files296035
+Node: Special FD296568
+Ref: Special FD-Footnote-1300165
+Node: Special Network300239
+Node: Special Caveats301089
+Node: Close Files And Pipes301885
+Ref: Close Files And Pipes-Footnote-1309046
+Ref: Close Files And Pipes-Footnote-2309194
+Node: Output Summary309344
+Node: Output exercises310341
+Node: Expressions311021
+Node: Values312206
+Node: Constants312882
+Node: Scalar Constants313562
+Ref: Scalar Constants-Footnote-1314421
+Node: Nondecimal-numbers314671
+Node: Regexp Constants317671
+Node: Using Constant Regexps318146
+Node: Variables321218
+Node: Using Variables321873
+Node: Assignment Options323597
+Node: Conversion325472
+Node: Strings And Numbers325996
+Ref: Strings And Numbers-Footnote-1329058
+Node: Locale influences conversions329167
+Ref: table-locale-affects331884
+Node: All Operators332472
+Node: Arithmetic Ops333102
+Node: Concatenation335607
+Ref: Concatenation-Footnote-1338426
+Node: Assignment Ops338532
+Ref: table-assign-ops343515
+Node: Increment Ops344818
+Node: Truth Values and Conditions348256
+Node: Truth Values349339
+Node: Typing and Comparison350388
+Node: Variable Typing351181
+Node: Comparison Operators354833
+Ref: table-relational-ops355243
+Node: POSIX String Comparison358793
+Ref: POSIX String Comparison-Footnote-1359877
+Node: Boolean Ops360015
+Ref: Boolean Ops-Footnote-1364090
+Node: Conditional Exp364181
+Node: Function Calls365908
+Node: Precedence369788
+Node: Locales373457
+Node: Expressions Summary375088
+Node: Patterns and Actions377629
+Node: Pattern Overview378745
+Node: Regexp Patterns380422
+Node: Expression Patterns380965
+Node: Ranges384745
+Node: BEGIN/END387851
+Node: Using BEGIN/END388613
+Ref: Using BEGIN/END-Footnote-1391349
+Node: I/O And BEGIN/END391455
+Node: BEGINFILE/ENDFILE393726
+Node: Empty396657
+Node: Using Shell Variables396974
+Node: Action Overview399257
+Node: Statements401584
+Node: If Statement403432
+Node: While Statement404930
+Node: Do Statement406974
+Node: For Statement408130
+Node: Switch Statement411282
+Node: Break Statement413670
+Node: Continue Statement415711
+Node: Next Statement417536
+Node: Nextfile Statement419926
+Node: Exit Statement422562
+Node: Built-in Variables424966
+Node: User-modified426093
+Ref: User-modified-Footnote-1433782
+Node: Auto-set433844
+Ref: Auto-set-Footnote-1446763
+Ref: Auto-set-Footnote-2446968
+Node: ARGC and ARGV447024
+Node: Pattern Action Summary450928
+Node: Arrays453151
+Node: Array Basics454700
+Node: Array Intro455526
+Ref: figure-array-elements457499
+Ref: Array Intro-Footnote-1460023
+Node: Reference to Elements460151
+Node: Assigning Elements462601
+Node: Array Example463092
+Node: Scanning an Array464824
+Node: Controlling Scanning467825
+Ref: Controlling Scanning-Footnote-1472998
+Node: Delete473314
+Ref: Delete-Footnote-1476065
+Node: Numeric Array Subscripts476122
+Node: Uninitialized Subscripts478305
+Node: Multidimensional479930
+Node: Multiscanning483043
+Node: Arrays of Arrays484632
+Node: Arrays Summary489295
+Node: Functions491400
+Node: Built-in492273
+Node: Calling Built-in493351
+Node: Numeric Functions495339
+Ref: Numeric Functions-Footnote-1500175
+Ref: Numeric Functions-Footnote-2500532
+Ref: Numeric Functions-Footnote-3500580
+Node: String Functions500849
+Ref: String Functions-Footnote-1523846
+Ref: String Functions-Footnote-2523975
+Ref: String Functions-Footnote-3524223
+Node: Gory Details524310
+Ref: table-sub-escapes526083
+Ref: table-sub-proposed527603
+Ref: table-posix-sub528967
+Ref: table-gensub-escapes530507
+Ref: Gory Details-Footnote-1531683
+Node: I/O Functions531834
+Ref: I/O Functions-Footnote-1538944
+Node: Time Functions539091
+Ref: Time Functions-Footnote-1549555
+Ref: Time Functions-Footnote-2549623
+Ref: Time Functions-Footnote-3549781
+Ref: Time Functions-Footnote-4549892
+Ref: Time Functions-Footnote-5550004
+Ref: Time Functions-Footnote-6550231
+Node: Bitwise Functions550497
+Ref: table-bitwise-ops551059
+Ref: Bitwise Functions-Footnote-1555304
+Node: Type Functions555488
+Node: I18N Functions556630
+Node: User-defined558275
+Node: Definition Syntax559079
+Ref: Definition Syntax-Footnote-1564390
+Node: Function Example564459
+Ref: Function Example-Footnote-1567099
+Node: Function Caveats567121
+Node: Calling A Function567639
+Node: Variable Scope568594
+Node: Pass By Value/Reference571582
+Node: Return Statement575092
+Node: Dynamic Typing578076
+Node: Indirect Calls579005
+Node: Functions Summary588718
+Node: Library Functions591257
+Ref: Library Functions-Footnote-1594875
+Ref: Library Functions-Footnote-2595018
+Node: Library Names595189
+Ref: Library Names-Footnote-1598662
+Ref: Library Names-Footnote-2598882
+Node: General Functions598968
+Node: Strtonum Function599996
+Node: Assert Function602776
+Node: Round Function606102
+Node: Cliff Random Function607643
+Node: Ordinal Functions608659
+Ref: Ordinal Functions-Footnote-1611724
+Ref: Ordinal Functions-Footnote-2611976
+Node: Join Function612187
+Ref: Join Function-Footnote-1613958
+Node: Getlocaltime Function614158
+Node: Readfile Function617894
+Node: Data File Management619733
+Node: Filetrans Function620365
+Node: Rewind Function624434
+Node: File Checking625992
+Ref: File Checking-Footnote-1627124
+Node: Empty Files627325
+Node: Ignoring Assigns629304
+Node: Getopt Function630858
+Ref: Getopt Function-Footnote-1642161
+Node: Passwd Functions642364
+Ref: Passwd Functions-Footnote-1651343
+Node: Group Functions651431
+Ref: Group Functions-Footnote-1659362
+Node: Walking Arrays659575
+Node: Library Functions Summary661178
+Node: Library exercises662566
+Node: Sample Programs663846
+Node: Running Examples664616
+Node: Clones665344
+Node: Cut Program666568
+Node: Egrep Program676426
+Ref: Egrep Program-Footnote-1684013
+Node: Id Program684123
+Node: Split Program687777
+Ref: Split Program-Footnote-1691315
+Node: Tee Program691443
+Node: Uniq Program694230
+Node: Wc Program701651
+Ref: Wc Program-Footnote-1705916
+Node: Miscellaneous Programs706008
+Node: Dupword Program707221
+Node: Alarm Program709252
+Node: Translate Program714056
+Ref: Translate Program-Footnote-1718447
+Ref: Translate Program-Footnote-2718717
+Node: Labels Program718851
+Ref: Labels Program-Footnote-1722212
+Node: Word Sorting722296
+Node: History Sorting726339
+Node: Extract Program728175
+Node: Simple Sed735711
+Node: Igawk Program738773
+Ref: Igawk Program-Footnote-1753077
+Ref: Igawk Program-Footnote-2753278
+Node: Anagram Program753416
+Node: Signature Program756484
+Node: Programs Summary757731
+Node: Programs Exercises758946
+Node: Advanced Features762597
+Node: Nondecimal Data764545
+Node: Array Sorting766122
+Node: Controlling Array Traversal766819
+Node: Array Sorting Functions775099
+Ref: Array Sorting Functions-Footnote-1779006
+Node: Two-way I/O779200
+Ref: Two-way I/O-Footnote-1784144
+Ref: Two-way I/O-Footnote-2784323
+Node: TCP/IP Networking784405
+Node: Profiling787250
+Node: Advanced Features Summary794801
+Node: Internationalization796665
+Node: I18N and L10N798145
+Node: Explaining gettext798831
+Ref: Explaining gettext-Footnote-1803857
+Ref: Explaining gettext-Footnote-2804041
+Node: Programmer i18n804206
+Ref: Programmer i18n-Footnote-1809000
+Node: Translator i18n809049
+Node: String Extraction809843
+Ref: String Extraction-Footnote-1810976
+Node: Printf Ordering811062
+Ref: Printf Ordering-Footnote-1813844
+Node: I18N Portability813908
+Ref: I18N Portability-Footnote-1816357
+Node: I18N Example816420
+Ref: I18N Example-Footnote-1819126
+Node: Gawk I18N819198
+Node: I18N Summary819836
+Node: Debugger821175
+Node: Debugging822197
+Node: Debugging Concepts822638
+Node: Debugging Terms824494
+Node: Awk Debugging827091
+Node: Sample Debugging Session827983
+Node: Debugger Invocation828503
+Node: Finding The Bug829836
+Node: List of Debugger Commands836318
+Node: Breakpoint Control837650
+Node: Debugger Execution Control841314
+Node: Viewing And Changing Data844674
+Node: Execution Stack848032
+Node: Debugger Info849545
+Node: Miscellaneous Debugger Commands853539
+Node: Readline Support858723
+Node: Limitations859615
+Node: Debugging Summary861889
+Node: Arbitrary Precision Arithmetic863057
+Node: Computer Arithmetic864544
+Ref: Computer Arithmetic-Footnote-1868931
+Node: Math Definitions868988
+Ref: table-ieee-formats872277
+Ref: Math Definitions-Footnote-1872817
+Node: MPFR features872920
+Node: FP Math Caution874537
+Ref: FP Math Caution-Footnote-1875587
+Node: Inexactness of computations875956
+Node: Inexact representation876904
+Node: Comparing FP Values878259
+Node: Errors accumulate879223
+Node: Getting Accuracy880656
+Node: Try To Round883315
+Node: Setting precision884214
+Ref: table-predefined-precision-strings884896
+Node: Setting the rounding mode886689
+Ref: table-gawk-rounding-modes887053
+Ref: Setting the rounding mode-Footnote-1890507
+Node: Arbitrary Precision Integers890686
+Ref: Arbitrary Precision Integers-Footnote-1894459
+Node: POSIX Floating Point Problems894608
+Ref: POSIX Floating Point Problems-Footnote-1898484
+Node: Floating point summary898522
+Node: Dynamic Extensions900726
+Node: Extension Intro902278
+Node: Plugin License903543
+Node: Extension Mechanism Outline904228
+Ref: figure-load-extension904652
+Ref: figure-load-new-function906137
+Ref: figure-call-new-function907139
+Node: Extension API Description909123
+Node: Extension API Functions Introduction910573
+Node: General Data Types915440
+Ref: General Data Types-Footnote-1921133
+Node: Requesting Values921432
+Ref: table-value-types-returned922169
+Node: Memory Allocation Functions923127
+Ref: Memory Allocation Functions-Footnote-1925874
+Node: Constructor Functions925970
+Node: Registration Functions927728
+Node: Extension Functions928413
+Node: Exit Callback Functions930715
+Node: Extension Version String931963
+Node: Input Parsers932613
+Node: Output Wrappers942427
+Node: Two-way processors946943
+Node: Printing Messages949147
+Ref: Printing Messages-Footnote-1950224
+Node: Updating `ERRNO'950376
+Node: Accessing Parameters951115
+Node: Symbol Table Access952345
+Node: Symbol table by name952859
+Node: Symbol table by cookie954835
+Ref: Symbol table by cookie-Footnote-1958968
+Node: Cached values959031
+Ref: Cached values-Footnote-1962535
+Node: Array Manipulation962626
+Ref: Array Manipulation-Footnote-1963724
+Node: Array Data Types963763
+Ref: Array Data Types-Footnote-1966466
+Node: Array Functions966558
+Node: Flattening Arrays970432
+Node: Creating Arrays977284
+Node: Extension API Variables982015
+Node: Extension Versioning982651
+Node: Extension API Informational Variables984552
+Node: Extension API Boilerplate985638
+Node: Finding Extensions989442
+Node: Extension Example990002
+Node: Internal File Description990732
+Node: Internal File Ops994823
+Ref: Internal File Ops-Footnote-11006255
+Node: Using Internal File Ops1006395
+Ref: Using Internal File Ops-Footnote-11008742
+Node: Extension Samples1009010
+Node: Extension Sample File Functions1010534
+Node: Extension Sample Fnmatch1018102
+Node: Extension Sample Fork1019584
+Node: Extension Sample Inplace1020797
+Node: Extension Sample Ord1022472
+Node: Extension Sample Readdir1023308
+Ref: table-readdir-file-types1024164
+Node: Extension Sample Revout1024963
+Node: Extension Sample Rev2way1025554
+Node: Extension Sample Read write array1026295
+Node: Extension Sample Readfile1028174
+Node: Extension Sample API Tests1029274
+Node: Extension Sample Time1029799
+Node: gawkextlib1031114
+Node: Extension summary1033927
+Node: Extension Exercises1037620
+Node: Language History1038342
+Node: V7/SVR3.11039985
+Node: SVR41042305
+Node: POSIX1043747
+Node: BTL1045133
+Node: POSIX/GNU1045867
+Node: Feature History1051583
+Node: Common Extensions1064674
+Node: Ranges and Locales1065986
+Ref: Ranges and Locales-Footnote-11070603
+Ref: Ranges and Locales-Footnote-21070630
+Ref: Ranges and Locales-Footnote-31070864
+Node: Contributors1071085
+Node: History summary1076510
+Node: Installation1077879
+Node: Gawk Distribution1078830
+Node: Getting1079314
+Node: Extracting1080138
+Node: Distribution contents1081780
+Node: Unix Installation1087550
+Node: Quick Installation1088167
+Node: Additional Configuration Options1090609
+Node: Configuration Philosophy1092347
+Node: Non-Unix Installation1094698
+Node: PC Installation1095156
+Node: PC Binary Installation1096467
+Node: PC Compiling1098315
+Ref: PC Compiling-Footnote-11101314
+Node: PC Testing1101419
+Node: PC Using1102595
+Node: Cygwin1106747
+Node: MSYS1107556
+Node: VMS Installation1108070
+Node: VMS Compilation1108866
+Ref: VMS Compilation-Footnote-11110088
+Node: VMS Dynamic Extensions1110146
+Node: VMS Installation Details1111519
+Node: VMS Running1113771
+Node: VMS GNV1116605
+Node: VMS Old Gawk1117328
+Node: Bugs1117798
+Node: Other Versions1121802
+Node: Installation summary1128029
+Node: Notes1129085
+Node: Compatibility Mode1129950
+Node: Additions1130732
+Node: Accessing The Source1131657
+Node: Adding Code1133093
+Node: New Ports1139271
+Node: Derived Files1143752
+Ref: Derived Files-Footnote-11148833
+Ref: Derived Files-Footnote-21148867
+Ref: Derived Files-Footnote-31149463
+Node: Future Extensions1149577
+Node: Implementation Limitations1150183
+Node: Extension Design1151431
+Node: Old Extension Problems1152585
+Ref: Old Extension Problems-Footnote-11154102
+Node: Extension New Mechanism Goals1154159
+Ref: Extension New Mechanism Goals-Footnote-11157519
+Node: Extension Other Design Decisions1157708
+Node: Extension Future Growth1159814
+Node: Old Extension Mechanism1160650
+Node: Notes summary1162412
+Node: Basic Concepts1163598
+Node: Basic High Level1164279
+Ref: figure-general-flow1164551
+Ref: figure-process-flow1165150
+Ref: Basic High Level-Footnote-11168379
+Node: Basic Data Typing1168564
+Node: Glossary1171892
+Node: Copying1197044
+Node: GNU Free Documentation License1234600
+Node: Index1259736
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 5f3d9e8e..6182c4c0 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -1424,29 +1424,27 @@ for a complete list of those who made important contributions to @command{gawk}.
 The @command{awk} language has evolved over the years. Full details are
 provided in @ref{Language History}.
 The language described in this @value{DOCUMENT}
-is often referred to as ``new @command{awk}'' (@command{nawk}).
+is often referred to as ``new @command{awk}''.
+By analogy, the original version of @command{awk} is
+referred to as ``old @command{awk}.''
 
-@cindex @command{awk}, versions of
-@cindex @command{nawk} utility
-@cindex @command{oawk} utility
-For some time after new @command{awk} was introduced, there were
-systems with multiple versions of @command{awk}.  Some systems had
-an @command{awk} utility that implemented the original version of the
-@command{awk} language and a @command{nawk} utility for the new version.
-Others had an @command{oawk} version for the ``old @command{awk}''
-language and plain @command{awk} for the new one.  Still others only
-had one version, which is usually the new one.
-
-Today, only Solaris systems still use an old @command{awk} for the
-default @command{awk} utility. (A more modern @command{awk} lives in
-@file{/usr/xpg6/bin} on these systems.)  All other modern systems use
-some version of new @command{awk}.@footnote{Many of these systems use
-@command{gawk} for their @command{awk} implementation!}
-
-It is likely that you already have some version of new @command{awk} on
-your system, which is what you should use when running your programs.
-(Of course, if you're reading this @value{DOCUMENT}, chances are good
-that you have @command{gawk}!)
+Today, on most systems, when you run the @command{awk} utility,
+you get some version of new @command{awk}.@footnote{Only
+Solaris systems still use an old @command{awk} for the
+default @command{awk} utility. A more modern @command{awk} lives in
+@file{/usr/xpg6/bin} on these systems.} If your system's standard
+@command{awk} is the old one, you will see something like this
+if you try the test program:
+
+@example
+$ @kbd{awk 1 /dev/null}
+@error{} awk: syntax error near line 1
+@error{} awk: bailing out near line 1
+@end example
+
+@noindent
+In this case, you should find a version of new @command{awk},
+or just install @command{gawk}!
 
 Throughout this @value{DOCUMENT}, whenever we refer to a language feature
 that should be available in any complete implementation of POSIX @command{awk},
@@ -2467,16 +2465,7 @@ BEGIN @{ print "Don't Panic!" @}
 @noindent
 After making this file executable (with the @command{chmod} utility),
 simply type @samp{advice}
-at the shell and the system arranges to run @command{awk}@footnote{The
-line beginning with @samp{#!} lists the full @value{FN} of an interpreter
-to run and a single optional initial command-line argument to pass to that
-interpreter.  The operating system then runs the interpreter with the given
-argument and the full argument list of the executed program.  The first argument
-in the list is the full @value{FN} of the @command{awk} program.
-The rest of the
-argument list contains either options to @command{awk}, or @value{DF}s,
-or both. Note that on many systems @command{awk} may be found in
-@file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had
+at the shell and the system arranges to run @command{awk} as if you had
 typed @samp{awk -f advice}:
 
 @example
@@ -2494,14 +2483,32 @@ Self-contained @command{awk} scripts are useful when you want to write a
 program that users can invoke without their having to know that the program is
 written in @command{awk}.
 
-@cindex sidebar, Portability Issues with @samp{#!}
+@cindex sidebar, Understanding @samp{#!}
 @ifdocbook
 @docbook
-<sidebar><title>Portability Issues with @samp{#!}</title>
+<sidebar><title>Understanding @samp{#!}</title>
 @end docbook
 
 @cindex portability, @code{#!} (executable scripts)
 
+@command{awk} is an @dfn{interpreted} language. This means that the
+@command{awk} utility reads your program and then processes your data
+according to the instructions in your program. (This is different
+from a @dfn{compiled} language such as C, where your program is first
+compiled into machine code that is executed directly by your system's
+hardware.)  The @command{awk} utility is thus termed an @dfn{interpreter}.
+Many modern languages are interperted.
+
+The line beginning with @samp{#!} lists the full @value{FN} of an
+interpreter to run and a single optional initial command-line argument
+to pass to that interpreter.  The operating system then runs the
+interpreter with the given argument and the full argument list of the
+executed program.  The first argument in the list is the full @value{FN}
+of the @command{awk} program.  The rest of the argument list contains
+either options to @command{awk}, or @value{DF}s, or both. Note that on
+many systems @command{awk} may be found in @file{/usr/bin} instead of
+in @file{/bin}. Caveat Emptor.
+
 Some systems limit the length of the interpreter name to 32 characters.
 Often, this can be dealt with by using a symbolic link.
 
@@ -2513,8 +2520,7 @@ of some sort from @command{awk}.
 
 @cindex @code{ARGC}/@code{ARGV} variables, portability and
 @cindex portability, @code{ARGV} variable
-Finally,
-the value of @code{ARGV[0]}
+Finally, the value of @code{ARGV[0]}
 (@pxref{Built-in Variables})
 varies depending upon your operating system.
 Some systems put @samp{awk} there, some put the full pathname
@@ -2530,11 +2536,29 @@ to provide your script name.
 
 @ifnotdocbook
 @cartouche
-@center @b{Portability Issues with @samp{#!}}
+@center @b{Understanding @samp{#!}}
 
 
 @cindex portability, @code{#!} (executable scripts)
 
+@command{awk} is an @dfn{interpreted} language. This means that the
+@command{awk} utility reads your program and then processes your data
+according to the instructions in your program. (This is different
+from a @dfn{compiled} language such as C, where your program is first
+compiled into machine code that is executed directly by your system's
+hardware.)  The @command{awk} utility is thus termed an @dfn{interpreter}.
+Many modern languages are interperted.
+
+The line beginning with @samp{#!} lists the full @value{FN} of an
+interpreter to run and a single optional initial command-line argument
+to pass to that interpreter.  The operating system then runs the
+interpreter with the given argument and the full argument list of the
+executed program.  The first argument in the list is the full @value{FN}
+of the @command{awk} program.  The rest of the argument list contains
+either options to @command{awk}, or @value{DF}s, or both. Note that on
+many systems @command{awk} may be found in @file{/usr/bin} instead of
+in @file{/bin}. Caveat Emptor.
+
 Some systems limit the length of the interpreter name to 32 characters.
 Often, this can be dealt with by using a symbolic link.
 
@@ -2546,8 +2570,7 @@ of some sort from @command{awk}.
 
 @cindex @code{ARGC}/@code{ARGV} variables, portability and
 @cindex portability, @code{ARGV} variable
-Finally,
-the value of @code{ARGV[0]}
+Finally, the value of @code{ARGV[0]}
 (@pxref{Built-in Variables})
 varies depending upon your operating system.
 Some systems put @samp{awk} there, some put the full pathname
@@ -2910,6 +2933,7 @@ of green crates shipped, the number of red boxes shipped, the number of
 orange bags shipped, and the number of blue packages shipped,
 respectively.  There are 16 entries, covering the 12 months of last year
 and the first four months of the current year.
+An empty line separates the data for the two years.
 
 @example
 @c file eg/data/inventory-shipped
@@ -3005,14 +3029,6 @@ you can come up with different ways to do the same things shown here:
 
 @itemize @value{BULLET}
 @item
-Print the length of the longest input line:
-
-@example
-awk '@{ if (length($0) > max) max = length($0) @}
-     END @{ print max @}' data
-@end example
-
-@item
 Print every line that is longer than 80 characters:
 
 @example
@@ -3022,6 +3038,14 @@ awk 'length($0) > 80' data
 The sole rule has a relational expression as its pattern and it has no
 action---so it uses the default action, printing the record.
 
+@item
+Print the length of the longest input line:
+
+@example
+awk '@{ if (length($0) > max) max = length($0) @}
+     END @{ print max @}' data
+@end example
+
 @cindex @command{expand} utility
 @item
 Print the length of the longest line in @file{data}:
@@ -3031,7 +3055,7 @@ expand data | awk '@{ if (x < length($0)) x = length($0) @}
               END @{ print "maximum line length is " x @}'
 @end example
 
-This example differs slightly from the first example in this list:
+This example differs slightly from the previous one:
 The input is processed by the @command{expand} utility to change TABs
 into spaces, so the widths compared are actually the right-margin columns,
 as opposed to the number of input characters on each line.
@@ -5282,14 +5306,15 @@ applies the @samp{*} symbol to the preceding @samp{h} and looks for matches
 of one @samp{p} followed by any number of @samp{h}s.  This also matches
 just @samp{p} if no @samp{h}s are present.
 
-The @samp{*} repeats the @emph{smallest} possible preceding expression.
-(Use parentheses if you want to repeat a larger expression.)  It finds
-as many repetitions as possible.  For example,
-@samp{awk '/\(c[ad][ad]*r x\)/ @{ print @}' sample}
-prints every record in @file{sample} containing a string of the form
-@samp{(car x)}, @samp{(cdr x)}, @samp{(cadr x)}, and so on.
-Notice the escaping of the parentheses by preceding them
-with backslashes.
+There are two subtle points to understand about how @samp{*} works.
+First, the @samp{*} applies only to the single preceding regular expression
+component (e.g., in @samp{ph*}, it applies just to the @samp{h}).
+To cause @samp{*} to apply to a larger sub-expression, use parentheses:
+@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph} and so on.
+
+Second, @samp{*} finds as many repetititons as possible. If the text
+to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of
+the @samp{h}s.
 
 @cindex @code{+} (plus sign), regexp operator
 @cindex plus sign (@code{+}), regexp operator
@@ -5298,12 +5323,6 @@ This symbol is similar to @samp{*}, except that the preceding expression must be
 matched at least once.  This means that @samp{wh+y}
 would match @samp{why} and @samp{whhy}, but not @samp{wy}, whereas
 @samp{wh*y} would match all three.
-The following is a simpler
-way of writing the last @samp{*} example:
-
-@example
-awk '/\(c[ad]+r x\)/ @{ print @}' sample
-@end example
 
 @cindex @code{?} (question mark), regexp operator
 @cindex question mark (@code{?}), regexp operator
@@ -15345,7 +15364,10 @@ array element value:
 @end docbook
 
 @noindent
-The pairs are shown in jumbled order because their order is irrelevant.
+The pairs are shown in jumbled order because their order is
+irrelevant.@footnote{The ordering will vary among @command{awk}
+implementations, which typically use hash tables to store array elements
+and values.}
 
 One advantage of associative arrays is that new pairs can be added
 at any time.  For example, suppose a tenth element is added to the array
@@ -15467,8 +15489,9 @@ English to French:
 Here we decided to translate the number one in both spelled-out and
 numeric form---thus illustrating that a single array can have both
 numbers and strings as indices.
-(In fact, array subscripts are always strings; this is discussed
-in more detail in
+(In fact, array subscripts are always strings.
+There are some subtleties to how numbers work when used as
+array subscripts; this is discussed in more detail in
 @ref{Numeric Array Subscripts}.)
 Here, the number @code{1} isn't double-quoted, since @command{awk}
 automatically converts it to a string.
@@ -19062,6 +19085,12 @@ them, i.e., to tell @command{awk} what they should do.
 @node Definition Syntax
 @subsection Function Definition Syntax
 
+@quotation
+It's entirely fair to say that the @command{awk} syntax for local
+variable definitions is appallingly awful
+@author Brian Kernighan
+@end quotation
+
 @c STARTOFRANGE fdef
 @cindex functions, defining
 Definitions of functions can appear anywhere between the rules of an
@@ -19101,7 +19130,7 @@ have a parameter with the same name as the function itself.
 In addition, according to the POSIX standard, function parameters
 cannot have the same name as one of the special built-in variables
 (@pxref{Built-in Variables}).  Not all versions of @command{awk} enforce
-this restriction.)
+this restriction.
 
 Local variables act like the empty string if referenced where a string
 value is required, and like zero if referenced where a numeric value
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 4b3dafb9..9534a557 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -1391,29 +1391,27 @@ for a complete list of those who made important contributions to @command{gawk}.
 The @command{awk} language has evolved over the years. Full details are
 provided in @ref{Language History}.
 The language described in this @value{DOCUMENT}
-is often referred to as ``new @command{awk}'' (@command{nawk}).
+is often referred to as ``new @command{awk}''.
+By analogy, the original version of @command{awk} is
+referred to as ``old @command{awk}.''
 
-@cindex @command{awk}, versions of
-@cindex @command{nawk} utility
-@cindex @command{oawk} utility
-For some time after new @command{awk} was introduced, there were
-systems with multiple versions of @command{awk}.  Some systems had
-an @command{awk} utility that implemented the original version of the
-@command{awk} language and a @command{nawk} utility for the new version.
-Others had an @command{oawk} version for the ``old @command{awk}''
-language and plain @command{awk} for the new one.  Still others only
-had one version, which is usually the new one.
-
-Today, only Solaris systems still use an old @command{awk} for the
-default @command{awk} utility. (A more modern @command{awk} lives in
-@file{/usr/xpg6/bin} on these systems.)  All other modern systems use
-some version of new @command{awk}.@footnote{Many of these systems use
-@command{gawk} for their @command{awk} implementation!}
-
-It is likely that you already have some version of new @command{awk} on
-your system, which is what you should use when running your programs.
-(Of course, if you're reading this @value{DOCUMENT}, chances are good
-that you have @command{gawk}!)
+Today, on most systems, when you run the @command{awk} utility,
+you get some version of new @command{awk}.@footnote{Only
+Solaris systems still use an old @command{awk} for the
+default @command{awk} utility. A more modern @command{awk} lives in
+@file{/usr/xpg6/bin} on these systems.} If your system's standard
+@command{awk} is the old one, you will see something like this
+if you try the test program:
+
+@example
+$ @kbd{awk 1 /dev/null}
+@error{} awk: syntax error near line 1
+@error{} awk: bailing out near line 1
+@end example
+
+@noindent
+In this case, you should find a version of new @command{awk},
+or just install @command{gawk}!
 
 Throughout this @value{DOCUMENT}, whenever we refer to a language feature
 that should be available in any complete implementation of POSIX @command{awk},
@@ -2434,16 +2432,7 @@ BEGIN @{ print "Don't Panic!" @}
 @noindent
 After making this file executable (with the @command{chmod} utility),
 simply type @samp{advice}
-at the shell and the system arranges to run @command{awk}@footnote{The
-line beginning with @samp{#!} lists the full @value{FN} of an interpreter
-to run and a single optional initial command-line argument to pass to that
-interpreter.  The operating system then runs the interpreter with the given
-argument and the full argument list of the executed program.  The first argument
-in the list is the full @value{FN} of the @command{awk} program.
-The rest of the
-argument list contains either options to @command{awk}, or @value{DF}s,
-or both. Note that on many systems @command{awk} may be found in
-@file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had
+at the shell and the system arranges to run @command{awk} as if you had
 typed @samp{awk -f advice}:
 
 @example
@@ -2461,9 +2450,27 @@ Self-contained @command{awk} scripts are useful when you want to write a
 program that users can invoke without their having to know that the program is
 written in @command{awk}.
 
-@sidebar Portability Issues with @samp{#!}
+@sidebar Understanding @samp{#!}
 @cindex portability, @code{#!} (executable scripts)
 
+@command{awk} is an @dfn{interpreted} language. This means that the
+@command{awk} utility reads your program and then processes your data
+according to the instructions in your program. (This is different
+from a @dfn{compiled} language such as C, where your program is first
+compiled into machine code that is executed directly by your system's
+hardware.)  The @command{awk} utility is thus termed an @dfn{interpreter}.
+Many modern languages are interperted.
+
+The line beginning with @samp{#!} lists the full @value{FN} of an
+interpreter to run and a single optional initial command-line argument
+to pass to that interpreter.  The operating system then runs the
+interpreter with the given argument and the full argument list of the
+executed program.  The first argument in the list is the full @value{FN}
+of the @command{awk} program.  The rest of the argument list contains
+either options to @command{awk}, or @value{DF}s, or both. Note that on
+many systems @command{awk} may be found in @file{/usr/bin} instead of
+in @file{/bin}. Caveat Emptor.
+
 Some systems limit the length of the interpreter name to 32 characters.
 Often, this can be dealt with by using a symbolic link.
 
@@ -2475,8 +2482,7 @@ of some sort from @command{awk}.
 
 @cindex @code{ARGC}/@code{ARGV} variables, portability and
 @cindex portability, @code{ARGV} variable
-Finally,
-the value of @code{ARGV[0]}
+Finally, the value of @code{ARGV[0]}
 (@pxref{Built-in Variables})
 varies depending upon your operating system.
 Some systems put @samp{awk} there, some put the full pathname
@@ -2838,6 +2844,7 @@ of green crates shipped, the number of red boxes shipped, the number of
 orange bags shipped, and the number of blue packages shipped,
 respectively.  There are 16 entries, covering the 12 months of last year
 and the first four months of the current year.
+An empty line separates the data for the two years.
 
 @example
 @c file eg/data/inventory-shipped
@@ -2933,14 +2940,6 @@ you can come up with different ways to do the same things shown here:
 
 @itemize @value{BULLET}
 @item
-Print the length of the longest input line:
-
-@example
-awk '@{ if (length($0) > max) max = length($0) @}
-     END @{ print max @}' data
-@end example
-
-@item
 Print every line that is longer than 80 characters:
 
 @example
@@ -2950,6 +2949,14 @@ awk 'length($0) > 80' data
 The sole rule has a relational expression as its pattern and it has no
 action---so it uses the default action, printing the record.
 
+@item
+Print the length of the longest input line:
+
+@example
+awk '@{ if (length($0) > max) max = length($0) @}
+     END @{ print max @}' data
+@end example
+
 @cindex @command{expand} utility
 @item
 Print the length of the longest line in @file{data}:
@@ -2959,7 +2966,7 @@ expand data | awk '@{ if (x < length($0)) x = length($0) @}
               END @{ print "maximum line length is " x @}'
 @end example
 
-This example differs slightly from the first example in this list:
+This example differs slightly from the previous one:
 The input is processed by the @command{expand} utility to change TABs
 into spaces, so the widths compared are actually the right-margin columns,
 as opposed to the number of input characters on each line.
@@ -5127,14 +5134,15 @@ applies the @samp{*} symbol to the preceding @samp{h} and looks for matches
 of one @samp{p} followed by any number of @samp{h}s.  This also matches
 just @samp{p} if no @samp{h}s are present.
 
-The @samp{*} repeats the @emph{smallest} possible preceding expression.
-(Use parentheses if you want to repeat a larger expression.)  It finds
-as many repetitions as possible.  For example,
-@samp{awk '/\(c[ad][ad]*r x\)/ @{ print @}' sample}
-prints every record in @file{sample} containing a string of the form
-@samp{(car x)}, @samp{(cdr x)}, @samp{(cadr x)}, and so on.
-Notice the escaping of the parentheses by preceding them
-with backslashes.
+There are two subtle points to understand about how @samp{*} works.
+First, the @samp{*} applies only to the single preceding regular expression
+component (e.g., in @samp{ph*}, it applies just to the @samp{h}).
+To cause @samp{*} to apply to a larger sub-expression, use parentheses:
+@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph} and so on.
+
+Second, @samp{*} finds as many repetititons as possible. If the text
+to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of
+the @samp{h}s.
 
 @cindex @code{+} (plus sign), regexp operator
 @cindex plus sign (@code{+}), regexp operator
@@ -5143,12 +5151,6 @@ This symbol is similar to @samp{*}, except that the preceding expression must be
 matched at least once.  This means that @samp{wh+y}
 would match @samp{why} and @samp{whhy}, but not @samp{wy}, whereas
 @samp{wh*y} would match all three.
-The following is a simpler
-way of writing the last @samp{*} example:
-
-@example
-awk '/\(c[ad]+r x\)/ @{ print @}' sample
-@end example
 
 @cindex @code{?} (question mark), regexp operator
 @cindex question mark (@code{?}), regexp operator
@@ -14650,7 +14652,10 @@ array element value:
 @end docbook
 
 @noindent
-The pairs are shown in jumbled order because their order is irrelevant.
+The pairs are shown in jumbled order because their order is
+irrelevant.@footnote{The ordering will vary among @command{awk}
+implementations, which typically use hash tables to store array elements
+and values.}
 
 One advantage of associative arrays is that new pairs can be added
 at any time.  For example, suppose a tenth element is added to the array
@@ -14772,8 +14777,9 @@ English to French:
 Here we decided to translate the number one in both spelled-out and
 numeric form---thus illustrating that a single array can have both
 numbers and strings as indices.
-(In fact, array subscripts are always strings; this is discussed
-in more detail in
+(In fact, array subscripts are always strings.
+There are some subtleties to how numbers work when used as
+array subscripts; this is discussed in more detail in
 @ref{Numeric Array Subscripts}.)
 Here, the number @code{1} isn't double-quoted, since @command{awk}
 automatically converts it to a string.
@@ -18206,6 +18212,12 @@ them, i.e., to tell @command{awk} what they should do.
 @node Definition Syntax
 @subsection Function Definition Syntax
 
+@quotation
+It's entirely fair to say that the @command{awk} syntax for local
+variable definitions is appallingly awful
+@author Brian Kernighan
+@end quotation
+
 @c STARTOFRANGE fdef
 @cindex functions, defining
 Definitions of functions can appear anywhere between the rules of an
@@ -18245,7 +18257,7 @@ have a parameter with the same name as the function itself.
 In addition, according to the POSIX standard, function parameters
 cannot have the same name as one of the special built-in variables
 (@pxref{Built-in Variables}).  Not all versions of @command{awk} enforce
-this restriction.)
+this restriction.
 
 Local variables act like the empty string if referenced where a string
 value is required, and like zero if referenced where a numeric value