Merge branch 'gawk-4.1-stable'

4 files changed, 179 insertions, 107 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index d1ea52eb..f91757ae 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,11 @@
+2014-05-25         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Edits through Appendix A.
+
+2014-05-24         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Staying current): New section.
+
 2014-05-22         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
 	* gawktexi.in (BEGINFILE/ENDFILE): Update doc for getline - any
diff --git a/doc/gawk.info b/doc/gawk.info
index 5dd1a6ca..a7326977 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -25098,7 +25098,7 @@ the POSIX specification.  Many long-time `awk' users learned `awk'
 programming with the original `awk' implementation in Version 7 Unix.
 (This implementation was the basis for `awk' in Berkeley Unix, through
 4.3-Reno.  Subsequent versions of Berkeley Unix, and some systems
-derived from 4.4BSD-Lite, use various versions of `gawk' for their
+derived from 4.4BSD-Lite, used various versions of `gawk' for their
 `awk'.)  This major node briefly describes the evolution of the `awk'
 language, with cross-references to other parts of the Info file where
 you can find more information.
@@ -25540,8 +25540,8 @@ in POSIX `awk', in the order they were added to `gawk'.
    * The `next file' statement became `nextfile' (*note Nextfile
      Statement::).
 
-   * The `fflush()' function from the Bell Laboratories research
-     version of `awk' (*note I/O Functions::).
+   * The `fflush()' function from Brian Kernighan's `awk' (then at Bell
+     Laboratories; *note I/O Functions::).
 
    * New command line options:
 
@@ -25549,8 +25549,9 @@ in POSIX `awk', in the order they were added to `gawk'.
           available in the original Version 7 Unix version of `awk'
           (*note V7/SVR3.1::).
 
-        - The `-m' option from the Bell Laboratories research version
-          of `awk' This was later removed.
+        - The `-m' option from Brian Kernighan's `awk'.  (He was still
+          at Bell Laboratories at the time.)  This was later removed
+          from both his `awk' and from `gawk'.
 
         - The `--re-interval' option to provide interval expressions in
           regexps (*note Regexp Operators::).
@@ -25561,7 +25562,7 @@ in POSIX `awk', in the order they were added to `gawk'.
    * The use of GNU Autoconf to control the configuration process
      (*note Quick Installation::).
 
-   * Amiga support.
+   * Amiga support.  This has since been removed.
 
 
    Version 3.1 of `gawk' introduced the following features:
@@ -25652,7 +25653,8 @@ in POSIX `awk', in the order they were added to `gawk'.
 
    * Tandem support. This was later removed.
 
-   * The Atari port became officially unsupported.
+   * The Atari port became officially unsupported and was later removed
+     entirely.
 
    * The source code changed to use ISO C standard-style function
      definitions.
@@ -25714,8 +25716,8 @@ in POSIX `awk', in the order they were added to `gawk'.
      output redirections (*note I/O Functions::).
 
    * The `isarray()' function which distinguishes if an item is an array
-     or not, to make it possible to traverse multidimensional arrays
-     (*note Type Functions::).
+     or not, to make it possible to traverse arrays of arrays (*note
+     Type Functions::).
 
    * The `patsplit()' function which gives the same capability as
      `FPAT', for splitting (*note String Functions::).
@@ -26016,8 +26018,8 @@ Info file, in approximate chronological order:
 
    * Michal Jaegermann provided the port to Atari systems and its
      documentation.  (This port is no longer supported.)  He continues
-     to provide portability checking with DEC Alpha systems, and has
-     done a lot of work to make sure `gawk' works on non-32-bit systems.
+     to provide portability checking, and has done a lot of work to
+     make sure `gawk' works on non-32-bit systems.
 
    * Fred Fish provided the port to Amiga systems and its documentation.
      (With Fred's sad passing, this is no longer supported.)
@@ -26082,8 +26084,8 @@ Info file, in approximate chronological order:
         - The modifications to convert `gawk' into a byte-code
           interpreter, including the debugger.
 
-        - The addition of true multidimensional arrays.  *note Arrays
-          of Arrays::.
+        - The addition of true arrays of arrays.  *note Arrays of
+          Arrays::.
 
         - The additional modifications for support of arbitrary
           precision arithmetic.
@@ -32161,7 +32163,7 @@ Index
                                                               (line  19)
 * next debugger command:                 Debugger Execution Control.
                                                               (line  43)
-* next file statement:                   Feature History.     (line 168)
+* next file statement:                   Feature History.     (line 169)
 * next statement <1>:                    Next Statement.      (line   6)
 * next statement:                        Boolean Ops.         (line  85)
 * next statement, BEGIN/END patterns and: I/O And BEGIN/END.  (line  37)
@@ -33679,74 +33681,74 @@ Node: Extension Sample API Tests1003868
 Node: Extension Sample Time1004393
 Node: gawkextlib1005708
 Node: Language History1008489
-Node: V7/SVR3.11010082
-Node: SVR41012402
-Node: POSIX1013844
-Node: BTL1015230
-Node: POSIX/GNU1015964
-Node: Feature History1021563
-Node: Common Extensions1034539
-Node: Ranges and Locales1035851
-Ref: Ranges and Locales-Footnote-11040468
-Ref: Ranges and Locales-Footnote-21040495
-Ref: Ranges and Locales-Footnote-31040729
-Node: Contributors1040950
-Node: Installation1046331
-Node: Gawk Distribution1047225
-Node: Getting1047709
-Node: Extracting1048535
-Node: Distribution contents1050227
-Node: Unix Installation1055948
-Node: Quick Installation1056565
-Node: Additional Configuration Options1059011
-Node: Configuration Philosophy1060747
-Node: Non-Unix Installation1063101
-Node: PC Installation1063559
-Node: PC Binary Installation1064870
-Node: PC Compiling1066718
-Node: PC Testing1069678
-Node: PC Using1070854
-Node: Cygwin1075022
-Node: MSYS1075831
-Node: VMS Installation1076345
-Node: VMS Compilation1077141
-Ref: VMS Compilation-Footnote-11078393
-Node: VMS Dynamic Extensions1078451
-Node: VMS Installation Details1079824
-Node: VMS Running1082075
-Node: VMS GNV1084909
-Node: VMS Old Gawk1085632
-Node: Bugs1086102
-Node: Other Versions1090020
-Node: Notes1096104
-Node: Compatibility Mode1096904
-Node: Additions1097687
-Node: Accessing The Source1098614
-Node: Adding Code1100054
-Node: New Ports1106099
-Node: Derived Files1110234
-Ref: Derived Files-Footnote-11115555
-Ref: Derived Files-Footnote-21115589
-Ref: Derived Files-Footnote-31116189
-Node: Future Extensions1116287
-Node: Implementation Limitations1116870
-Node: Extension Design1118118
-Node: Old Extension Problems1119272
-Ref: Old Extension Problems-Footnote-11120780
-Node: Extension New Mechanism Goals1120837
-Ref: Extension New Mechanism Goals-Footnote-11124202
-Node: Extension Other Design Decisions1124388
-Node: Extension Future Growth1126494
-Node: Old Extension Mechanism1127330
-Node: Basic Concepts1129070
-Node: Basic High Level1129751
-Ref: figure-general-flow1130023
-Ref: figure-process-flow1130622
-Ref: Basic High Level-Footnote-11133851
-Node: Basic Data Typing1134036
-Node: Glossary1137391
-Node: Copying1162622
-Node: GNU Free Documentation License1200178
-Node: Index1225314
+Node: V7/SVR3.11010083
+Node: SVR41012403
+Node: POSIX1013845
+Node: BTL1015231
+Node: POSIX/GNU1015965
+Node: Feature History1021564
+Node: Common Extensions1034676
+Node: Ranges and Locales1035988
+Ref: Ranges and Locales-Footnote-11040605
+Ref: Ranges and Locales-Footnote-21040632
+Ref: Ranges and Locales-Footnote-31040866
+Node: Contributors1041087
+Node: Installation1046438
+Node: Gawk Distribution1047332
+Node: Getting1047816
+Node: Extracting1048642
+Node: Distribution contents1050334
+Node: Unix Installation1056055
+Node: Quick Installation1056672
+Node: Additional Configuration Options1059118
+Node: Configuration Philosophy1060854
+Node: Non-Unix Installation1063208
+Node: PC Installation1063666
+Node: PC Binary Installation1064977
+Node: PC Compiling1066825
+Node: PC Testing1069785
+Node: PC Using1070961
+Node: Cygwin1075129
+Node: MSYS1075938
+Node: VMS Installation1076452
+Node: VMS Compilation1077248
+Ref: VMS Compilation-Footnote-11078500
+Node: VMS Dynamic Extensions1078558
+Node: VMS Installation Details1079931
+Node: VMS Running1082182
+Node: VMS GNV1085016
+Node: VMS Old Gawk1085739
+Node: Bugs1086209
+Node: Other Versions1090127
+Node: Notes1096211
+Node: Compatibility Mode1097011
+Node: Additions1097794
+Node: Accessing The Source1098721
+Node: Adding Code1100161
+Node: New Ports1106206
+Node: Derived Files1110341
+Ref: Derived Files-Footnote-11115662
+Ref: Derived Files-Footnote-21115696
+Ref: Derived Files-Footnote-31116296
+Node: Future Extensions1116394
+Node: Implementation Limitations1116977
+Node: Extension Design1118225
+Node: Old Extension Problems1119379
+Ref: Old Extension Problems-Footnote-11120887
+Node: Extension New Mechanism Goals1120944
+Ref: Extension New Mechanism Goals-Footnote-11124309
+Node: Extension Other Design Decisions1124495
+Node: Extension Future Growth1126601
+Node: Old Extension Mechanism1127437
+Node: Basic Concepts1129177
+Node: Basic High Level1129858
+Ref: figure-general-flow1130130
+Ref: figure-process-flow1130729
+Ref: Basic High Level-Footnote-11133958
+Node: Basic Data Typing1134143
+Node: Glossary1137498
+Node: Copying1162729
+Node: GNU Free Documentation License1200285
+Node: Index1225421
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 531b85b1..cec42d29 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -1272,6 +1272,9 @@ has been removed.)
 * Conventions::                 Typographical Conventions.
 * Manual History::              Brief history of the GNU project and this
                                 @value{DOCUMENT}.
+@ifset FOR_PRINT
+* Staying current::             How to keep up.
+@end ifset
 * How To Contribute::           Helping to save the world.
 * Acknowledgments::             Acknowledgments.
 @end menu
@@ -1864,6 +1867,20 @@ version comes with the @command{gawk} distribution from the FSF.  If you
 find an error in this @value{DOCUMENT}, please report it!  @xref{Bugs},
 for information on submitting problem reports electronically.
 
+@ifset FOR_PRINT
+@node Staying current
+@unnumberedsec How to Stay Current
+
+It may be you have a version of @command{gawk} which is newer than the
+one described in this @value{DOCUMENT}.  To find out what has changed,
+you should first look at the @file{NEWS} file in the @command{gawk}
+distribution, which provides a high level summary of what changed in
+each release.
+
+You can then look at the @uref{http://www.gnu.org/software/gawk/manual/,
+online version} of this @value{DOCUMENT} to read about any new features.
+@end ifset
+
 @ifclear FOR_PRINT
 @node How To Contribute
 @unnumberedsec How to Contribute
@@ -34057,12 +34074,20 @@ which follows the POSIX specification.  Many long-time @command{awk}
 users learned @command{awk} programming with the original @command{awk}
 implementation in Version 7 Unix.  (This implementation was the basis for
 @command{awk} in Berkeley Unix, through 4.3-Reno.  Subsequent versions
-of Berkeley Unix, and some systems derived from 4.4BSD-Lite, use various
+of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various
 versions of @command{gawk} for their @command{awk}.)  This @value{CHAPTER}
 briefly describes the evolution of the @command{awk} language, with
 cross-references to other parts of the @value{DOCUMENT} where you can
 find more information.
 
+@ifset FOR_PRINT
+To save space, we have omitted
+information on the history of features in @command{gawk} from this
+edition. You can find it in the
+@uref{http://www.gnu.org/software/gawk/manual/html_node/Feature-History.html,
+online documentation}.
+@end ifset
+
 @menu
 * V7/SVR3.1::                   The major changes between V7 and System V
                                 Release 3.1.
@@ -34652,6 +34677,8 @@ GCC for VAX and Alpha has not been tested for a while.
 @c ENDOFRANGE exgnot
 @c ENDOFRANGE posnot
 
+@c This does not need to be in the formal book.
+@ifclear FOR_PRINT
 @node Feature History
 @appendixsec History of @command{gawk} Features
 
@@ -34816,9 +34843,10 @@ The @code{next file} statement became @code{nextfile}
 (@pxref{Nextfile Statement}).
 
 @item
-The @code{fflush()} function from the
-Bell Laboratories research version of @command{awk}
-(@pxref{I/O Functions}).
+The @code{fflush()} function from
+Brian Kernighan's @command{awk}
+(then at Bell Laboratories;
+@pxref{I/O Functions}).
 
 @item
 New command line options:
@@ -34831,9 +34859,9 @@ the original Version 7 Unix version of @command{awk}
 (@pxref{V7/SVR3.1}).
 
 @item
-The @option{-m} option from the
-Bell Laboratories research version of @command{awk}
-This was later removed.
+The @option{-m} option from Brian Kernighan's @command{awk}.  (He was
+still at Bell Laboratories at the time.)  This was later removed from
+both his @command{awk} and from @command{gawk}.
 
 @item
 The @option{--re-interval} option to provide interval expressions in regexps
@@ -34850,6 +34878,7 @@ The use of GNU Autoconf to control the configuration process
 
 @item
 Amiga support.
+This has since been removed.
 
 @end itemize
 
@@ -34986,7 +35015,8 @@ BeOS support. This was later removed.
 Tandem support. This was later removed.
 
 @item
-The Atari port became officially unsupported.
+The Atari port became officially unsupported and was
+later removed entirely.
 
 @item
 The source code changed to use ISO C standard-style function definitions.
@@ -35079,7 +35109,7 @@ flush all open output redirections
 @item
 The @code{isarray()}
 function which distinguishes if an item is an array
-or not, to make it possible to traverse multidimensional arrays
+or not, to make it possible to traverse arrays of arrays
 (@pxref{Type Functions}).
 
 @item
@@ -35257,6 +35287,7 @@ The dynamic extension interface was completely redone
 @end itemize
 
 @c XXX ADD MORE STUFF HERE
+@end ifclear
 
 @node Common Extensions
 @appendixsec Common Extensions Summary
@@ -35483,8 +35514,8 @@ provided the initial port to OS/2 and its documentation.
 Michal Jaegermann
 provided the port to Atari systems and its documentation.
 (This port is no longer supported.)
-He continues to provide portability checking with DEC Alpha
-systems, and has done a lot of work to make sure @command{gawk}
+He continues to provide portability checking,
+and has done a lot of work to make sure @command{gawk}
 works on non-32-bit systems.
 
 @item
@@ -35603,7 +35634,7 @@ The modifications to convert @command{gawk}
 into a byte-code interpreter, including the debugger.
 
 @item
-The addition of true multidimensional arrays.
+The addition of true arrays of arrays.
 @ref{Arrays of Arrays}.
 
 @item
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 16572bb2..ff5d59fc 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -1267,6 +1267,9 @@ has been removed.)
 * Conventions::                 Typographical Conventions.
 * Manual History::              Brief history of the GNU project and this
                                 @value{DOCUMENT}.
+@ifset FOR_PRINT
+* Staying current::             How to keep up.
+@end ifset
 * How To Contribute::           Helping to save the world.
 * Acknowledgments::             Acknowledgments.
 @end menu
@@ -1831,6 +1834,20 @@ version comes with the @command{gawk} distribution from the FSF.  If you
 find an error in this @value{DOCUMENT}, please report it!  @xref{Bugs},
 for information on submitting problem reports electronically.
 
+@ifset FOR_PRINT
+@node Staying current
+@unnumberedsec How to Stay Current
+
+It may be you have a version of @command{gawk} which is newer than the
+one described in this @value{DOCUMENT}.  To find out what has changed,
+you should first look at the @file{NEWS} file in the @command{gawk}
+distribution, which provides a high level summary of what changed in
+each release.
+
+You can then look at the @uref{http://www.gnu.org/software/gawk/manual/,
+online version} of this @value{DOCUMENT} to read about any new features.
+@end ifset
+
 @ifclear FOR_PRINT
 @node How To Contribute
 @unnumberedsec How to Contribute
@@ -33201,12 +33218,20 @@ which follows the POSIX specification.  Many long-time @command{awk}
 users learned @command{awk} programming with the original @command{awk}
 implementation in Version 7 Unix.  (This implementation was the basis for
 @command{awk} in Berkeley Unix, through 4.3-Reno.  Subsequent versions
-of Berkeley Unix, and some systems derived from 4.4BSD-Lite, use various
+of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various
 versions of @command{gawk} for their @command{awk}.)  This @value{CHAPTER}
 briefly describes the evolution of the @command{awk} language, with
 cross-references to other parts of the @value{DOCUMENT} where you can
 find more information.
 
+@ifset FOR_PRINT
+To save space, we have omitted
+information on the history of features in @command{gawk} from this
+edition. You can find it in the
+@uref{http://www.gnu.org/software/gawk/manual/html_node/Feature-History.html,
+online documentation}.
+@end ifset
+
 @menu
 * V7/SVR3.1::                   The major changes between V7 and System V
                                 Release 3.1.
@@ -33796,6 +33821,8 @@ GCC for VAX and Alpha has not been tested for a while.
 @c ENDOFRANGE exgnot
 @c ENDOFRANGE posnot
 
+@c This does not need to be in the formal book.
+@ifclear FOR_PRINT
 @node Feature History
 @appendixsec History of @command{gawk} Features
 
@@ -33960,9 +33987,10 @@ The @code{next file} statement became @code{nextfile}
 (@pxref{Nextfile Statement}).
 
 @item
-The @code{fflush()} function from the
-Bell Laboratories research version of @command{awk}
-(@pxref{I/O Functions}).
+The @code{fflush()} function from
+Brian Kernighan's @command{awk}
+(then at Bell Laboratories;
+@pxref{I/O Functions}).
 
 @item
 New command line options:
@@ -33975,9 +34003,9 @@ the original Version 7 Unix version of @command{awk}
 (@pxref{V7/SVR3.1}).
 
 @item
-The @option{-m} option from the
-Bell Laboratories research version of @command{awk}
-This was later removed.
+The @option{-m} option from Brian Kernighan's @command{awk}.  (He was
+still at Bell Laboratories at the time.)  This was later removed from
+both his @command{awk} and from @command{gawk}.
 
 @item
 The @option{--re-interval} option to provide interval expressions in regexps
@@ -33994,6 +34022,7 @@ The use of GNU Autoconf to control the configuration process
 
 @item
 Amiga support.
+This has since been removed.
 
 @end itemize
 
@@ -34130,7 +34159,8 @@ BeOS support. This was later removed.
 Tandem support. This was later removed.
 
 @item
-The Atari port became officially unsupported.
+The Atari port became officially unsupported and was
+later removed entirely.
 
 @item
 The source code changed to use ISO C standard-style function definitions.
@@ -34223,7 +34253,7 @@ flush all open output redirections
 @item
 The @code{isarray()}
 function which distinguishes if an item is an array
-or not, to make it possible to traverse multidimensional arrays
+or not, to make it possible to traverse arrays of arrays
 (@pxref{Type Functions}).
 
 @item
@@ -34401,6 +34431,7 @@ The dynamic extension interface was completely redone
 @end itemize
 
 @c XXX ADD MORE STUFF HERE
+@end ifclear
 
 @node Common Extensions
 @appendixsec Common Extensions Summary
@@ -34627,8 +34658,8 @@ provided the initial port to OS/2 and its documentation.
 Michal Jaegermann
 provided the port to Atari systems and its documentation.
 (This port is no longer supported.)
-He continues to provide portability checking with DEC Alpha
-systems, and has done a lot of work to make sure @command{gawk}
+He continues to provide portability checking,
+and has done a lot of work to make sure @command{gawk}
 works on non-32-bit systems.
 
 @item
@@ -34747,7 +34778,7 @@ The modifications to convert @command{gawk}
 into a byte-code interpreter, including the debugger.
 
 @item
-The addition of true multidimensional arrays.
+The addition of true arrays of arrays.
 @ref{Arrays of Arrays}.
 
 @item