Doc updates, getting ready for release.

9 files changed, 321 insertions, 117 deletions

diff --git a/ChangeLog b/ChangeLog
index 680d1ba9..c24341e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,7 @@
 2017-08-16         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* config.guess: Update from GNULIB.
+	* NEWS, README: Updated in preparation for release.
 
 2017-08-16         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
diff --git a/NEWS b/NEWS
index a999492c..72b69c17 100644
--- a/NEWS
+++ b/NEWS
@@ -1,11 +1,11 @@
-   Copyright (C) 2010, 2011, 2012, 2013, 2014, 2015, 2016,
+   Copyright (C) 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017
    Free Software Foundation, Inc.
    
    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.
 
-Changes from 4.1.x to 4.2.0
+Changes from 4.1.4 to 4.2.0
 ---------------------------
 
 1. If not in POSIX mode, changes to ENVIRON are reflected into
@@ -37,7 +37,7 @@ Changes from 4.1.x to 4.2.0
 8. MirBSD is no longer supported.
 
 9. Pretty printing now preserves comments and places them into the
-    pretty-printed file.
+   pretty-printed file.
 
 10. `make install' now installs shell startup files
     $sysconfdir/profile.d/gawk.{csh,sh} containing shell functions to
diff --git a/README b/README
index 11ff38cc..93c4987b 100644
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
   Copyright (C) 2005, 2006, 2007, 2009, 2010, 2011, 2012, 2013, 2014, 2015,
-  2016, Free Software Foundation, Inc.
+  2016, 2017 Free Software Foundation, Inc.
   
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
@@ -7,11 +7,11 @@
 
 README:
 
-This is GNU Awk 4.1.4. It is upwardly compatible with Brian Kernighan's
+This is GNU Awk 4.2.0. It is upwardly compatible with Brian Kernighan's
 version of Unix awk.  It is almost completely compliant with the
 2008 POSIX 1003.1 standard for awk. (See the note below about POSIX.)
 
-This is a bug-fix release. See NEWS and ChangeLog for details.
+This is a major release. See NEWS and ChangeLog for details.
 
 Work to be done is described briefly in the TODO file, which is available
 only in the 'master' branch in the Git repo.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 86c1d130..e6dd8ea0 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2017-08-16         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Update history of features appendix section.
+	* wordlist, worldlist2: Add more words.
+
 2017-08-13         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in, gawk.1, awkcard.in: Update versions and
diff --git a/doc/gawk.info b/doc/gawk.info
index 9031d5e7..53d45a11 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -28034,9 +28034,9 @@ POSIX 'awk', in the order they were added to 'gawk'.
 
         - MIPS RiscOS
 
-        - MS-DOS with Microsoft Compiler
+        - MS-DOS with the Microsoft Compiler
 
-        - MS-Windows with Microsoft Compiler
+        - MS-Windows with the Microsoft Compiler
 
         - NeXT
 
@@ -28090,23 +28090,32 @@ POSIX 'awk', in the order they were added to 'gawk'.
 
    * Support for Ultrix was removed.
 
-   Version 4.2 introduced the following changes:
+   Version 4.2 of 'gawk' introduced the following changes:
 
    * Changes to 'ENVIRON' are reflected into 'gawk''s environment and
      that of programs that it runs.  *Note Auto-set::.
 
-   * The 'PROCINFO["argv"' array.  *Note Auto-set::.
+   * 'FIELDWIDTHS' was enhanced to allow skipping characters before
+     assigning a value to a field (*note Splitting By Content::).
 
-   * The '--pretty-print' option no longer runs the 'awk' program too.
-     *Note Options::.
-
-   * The 'igawk' program and its manual page are no longer installed
-     when 'gawk' is built.  *Note Igawk Program::.
+   * The 'PROCINFO["argv"]' array.  *Note Auto-set::.
 
    * The maximum number of hexadecimal digits in '\x' escapes is now
      two.  *Note Escape Sequences::.
 
-   * Nonfatal output with 'print' and 'printf'.  *Note Nonfatal::.
+   * Strongly typed regexp constants of the form '@/.../' (*note Strong
+     Regexp Constants::).
+
+   * The bitwise functions changed, making negative arguments into a
+     fatal error (*note Bitwise Functions::).
+
+   * The 'mktime()' function now accepts an optional second argument
+     (*note Time Functions::).
+
+   * The 'typeof()' function (*note Type Functions::).
+
+   * Optimizations are enabled by default.  Use '-s' / '--no-optimize'
+     to disable optimizations.
 
    * For many years, POSIX specified that default field splitting only
      allowed spaces and tabs to separate fields, and this was how 'gawk'
@@ -28114,10 +28123,44 @@ POSIX 'awk', in the order they were added to 'gawk'.
      historical behavior, and now default field splitting with '--posix'
      also allows newlines to separate fields.
 
+   * Nonfatal output with 'print' and 'printf'.  *Note Nonfatal::.
+
+   * Retryable I/O via 'PROCINFO[INPUT-FILE, "RETRY"]'; (*note Retrying
+     Input::).
+
+   * Changes to the pretty-printer (*note Profiling::):
+
+        - The '--pretty-print' option no longer runs the 'awk' program
+          too.
+
+        - Comments in the source program are preserved and placed into
+          the output file.
+
+        - Explicit parentheses for expressions in the input are
+          preserved in the generated output.
+
+   * Improvements to the extension API (*note Dynamic Extensions::):
+
+        - The 'get_file()' function to access open redirections.
+
+        - The 'nonfatal()' function for generating nonfatal error
+          messages.
+
+        - Support for GMP and MPFR values.
+
+        - Input parsers can now override the default field parsing
+          mechanism by specifying explicit locations.
+
    * Support for MirBSD was removed.
 
    * Support for GNU/Linux on Alpha was removed.
 
+   * Shell startup files are supplied with the distribution and
+     installed by 'make install' (*note Shell Startup Files::).
+
+   * The 'igawk' program and its manual page are no longer installed
+     when 'gawk' is built.  *Note Igawk Program::.
+
 
 File: gawk.info,  Node: Common Extensions,  Next: Ranges and Locales,  Prev: Feature History,  Up: Language History
 
@@ -36304,74 +36347,74 @@ Node: POSIX1113185
 Node: BTL1114564
 Node: POSIX/GNU1115293
 Node: Feature History1121071
-Node: Common Extensions1135436
-Node: Ranges and Locales1136719
-Ref: Ranges and Locales-Footnote-11141335
-Ref: Ranges and Locales-Footnote-21141362
-Ref: Ranges and Locales-Footnote-31141597
-Node: Contributors1141818
-Node: History summary1147446
-Node: Installation1148826
-Node: Gawk Distribution1149770
-Node: Getting1150254
-Node: Extracting1151215
-Node: Distribution contents1152853
-Node: Unix Installation1159195
-Node: Quick Installation1159877
-Node: Shell Startup Files1162291
-Node: Additional Configuration Options1163380
-Node: Configuration Philosophy1165369
-Node: Non-Unix Installation1167738
-Node: PC Installation1168198
-Node: PC Binary Installation1169036
-Node: PC Compiling1169471
-Node: PC Using1170588
-Node: Cygwin1173633
-Node: MSYS1174403
-Node: VMS Installation1174904
-Node: VMS Compilation1175695
-Ref: VMS Compilation-Footnote-11176924
-Node: VMS Dynamic Extensions1176982
-Node: VMS Installation Details1178667
-Node: VMS Running1180920
-Node: VMS GNV1185199
-Node: VMS Old Gawk1185934
-Node: Bugs1186405
-Node: Bug address1187068
-Node: Usenet1189465
-Node: Maintainers1190242
-Node: Other Versions1191503
-Node: Installation summary1198087
-Node: Notes1199122
-Node: Compatibility Mode1199987
-Node: Additions1200769
-Node: Accessing The Source1201694
-Node: Adding Code1203129
-Node: New Ports1209347
-Node: Derived Files1213835
-Ref: Derived Files-Footnote-11219320
-Ref: Derived Files-Footnote-21219355
-Ref: Derived Files-Footnote-31219953
-Node: Future Extensions1220067
-Node: Implementation Limitations1220725
-Node: Extension Design1221908
-Node: Old Extension Problems1223062
-Ref: Old Extension Problems-Footnote-11224580
-Node: Extension New Mechanism Goals1224637
-Ref: Extension New Mechanism Goals-Footnote-11228001
-Node: Extension Other Design Decisions1228190
-Node: Extension Future Growth1230303
-Node: Old Extension Mechanism1231139
-Node: Notes summary1232902
-Node: Basic Concepts1234084
-Node: Basic High Level1234765
-Ref: figure-general-flow1235047
-Ref: figure-process-flow1235732
-Ref: Basic High Level-Footnote-11239033
-Node: Basic Data Typing1239218
-Node: Glossary1242546
-Node: Copying1274493
-Node: GNU Free Documentation License1312032
-Node: Index1337150
+Node: Common Extensions1136930
+Node: Ranges and Locales1138213
+Ref: Ranges and Locales-Footnote-11142829
+Ref: Ranges and Locales-Footnote-21142856
+Ref: Ranges and Locales-Footnote-31143091
+Node: Contributors1143312
+Node: History summary1148940
+Node: Installation1150320
+Node: Gawk Distribution1151264
+Node: Getting1151748
+Node: Extracting1152709
+Node: Distribution contents1154347
+Node: Unix Installation1160689
+Node: Quick Installation1161371
+Node: Shell Startup Files1163785
+Node: Additional Configuration Options1164874
+Node: Configuration Philosophy1166863
+Node: Non-Unix Installation1169232
+Node: PC Installation1169692
+Node: PC Binary Installation1170530
+Node: PC Compiling1170965
+Node: PC Using1172082
+Node: Cygwin1175127
+Node: MSYS1175897
+Node: VMS Installation1176398
+Node: VMS Compilation1177189
+Ref: VMS Compilation-Footnote-11178418
+Node: VMS Dynamic Extensions1178476
+Node: VMS Installation Details1180161
+Node: VMS Running1182414
+Node: VMS GNV1186693
+Node: VMS Old Gawk1187428
+Node: Bugs1187899
+Node: Bug address1188562
+Node: Usenet1190959
+Node: Maintainers1191736
+Node: Other Versions1192997
+Node: Installation summary1199581
+Node: Notes1200616
+Node: Compatibility Mode1201481
+Node: Additions1202263
+Node: Accessing The Source1203188
+Node: Adding Code1204623
+Node: New Ports1210841
+Node: Derived Files1215329
+Ref: Derived Files-Footnote-11220814
+Ref: Derived Files-Footnote-21220849
+Ref: Derived Files-Footnote-31221447
+Node: Future Extensions1221561
+Node: Implementation Limitations1222219
+Node: Extension Design1223402
+Node: Old Extension Problems1224556
+Ref: Old Extension Problems-Footnote-11226074
+Node: Extension New Mechanism Goals1226131
+Ref: Extension New Mechanism Goals-Footnote-11229495
+Node: Extension Other Design Decisions1229684
+Node: Extension Future Growth1231797
+Node: Old Extension Mechanism1232633
+Node: Notes summary1234396
+Node: Basic Concepts1235578
+Node: Basic High Level1236259
+Ref: figure-general-flow1236541
+Ref: figure-process-flow1237226
+Ref: Basic High Level-Footnote-11240527
+Node: Basic Data Typing1240712
+Node: Glossary1244040
+Node: Copying1275987
+Node: GNU Free Documentation License1313526
+Node: Index1338644
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 9c36c107..20c82251 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -37586,7 +37586,9 @@ I've tried to follow this general order, esp.@: for the 3.0 and 3.1 sections:
        new keywords
        new command-line options
        behavioral changes
-       new ports
+       extension API changes
+       new / deprecated / removed ports
+       installation time stuff
 Within each category, be alphabetical.
 @end ignore
 
@@ -38098,10 +38100,10 @@ Cray
 MIPS RiscOS
 
 @item
-MS-DOS with Microsoft Compiler
+MS-DOS with the Microsoft Compiler
 
 @item
-MS-Windows with Microsoft Compiler
+MS-Windows with the Microsoft Compiler
 
 @item
 NeXT
@@ -38186,7 +38188,7 @@ Support for Ultrix was removed.
 
 @end itemize
 
-Version 4.2 introduced the following changes:
+Version 4.2 of @command{gawk} introduced the following changes:
 
 @itemize @bullet
 @item
@@ -38195,18 +38197,26 @@ environment and that of programs that it runs.
 @xref{Auto-set}.
 
 @item
-The @code{PROCINFO["argv"} array.
+@code{FIELDWIDTHS} was enhanced to allow skipping characters
+before assigning a value to a field
+(@pxref{Splitting By Content}).
+
+@item
+The @code{PROCINFO["argv"]} array.
 @xref{Auto-set}.
 
 @item
-The @option{--pretty-print} option no longer runs the @command{awk}
-program too.
-@xref{Options}.
+The maximum number of hexadecimal digits in @samp{\x} escapes
+is now two.
+@xref{Escape Sequences}.
 
 @item
-The @command{igawk} program and its manual page are no longer
-installed when @command{gawk} is built.
-@xref{Igawk Program}.
+Strongly typed regexp constants of the form @samp{@@/@dots{}/}
+(@pxref{Strong Regexp Constants}).
+
+@item
+The bitwise functions changed, making negative arguments into
+a fatal error (@pxref{Bitwise Functions}).
 
 @ifset INTDIV
 @item
@@ -38215,13 +38225,16 @@ The @code{intdiv0()} function.
 @end ifset
 
 @item
-The maximum number of hexadecimal digits in @samp{\x} escapes
-is now two.
-@xref{Escape Sequences}.
+The @code{mktime()} function now accepts an optional
+second argument
+(@pxref{Time Functions}).
 
 @item
-Nonfatal output with @code{print} and @code{printf}.
-@xref{Nonfatal}.
+The @code{typeof()} function (@pxref{Type Functions}).
+
+@item
+Optimizations are enabled by default. Use @option{-s} /
+@option{--no-optimize} to disable optimizations.
 
 @item
 For many years, POSIX specified that default field splitting
@@ -38232,10 +38245,66 @@ field splitting with @option{--posix} also allows newlines to
 separate fields.
 
 @item
+Nonfatal output with @code{print} and @code{printf}.
+@xref{Nonfatal}.
+
+@item
+Retryable I/O via @code{PROCINFO[@var{input-file}, "RETRY"]};
+(@pxref{Retrying Input}).
+
+@item
+Changes to the pretty-printer (@pxref{Profiling}):
+
+@c nested table
+@itemize @value{MINUS}
+@item
+The @option{--pretty-print} option no longer runs the @command{awk}
+program too.
+
+@item
+Comments in the source program are preserved and placed into the
+output file.
+
+@item
+Explicit parentheses for expressions
+in the input are preserved in the generated output.
+@end itemize
+
+@item
+Improvements to the extension API
+(@pxref{Dynamic Extensions}):
+
+@c nested
+@itemize @value{MINUS}
+@item
+The @code{get_file()} function to access open redirections.
+
+@item
+The @code{nonfatal()} function for generating nonfatal error messages.
+
+@item
+Support for GMP and MPFR values.
+
+@item
+Input parsers can now override the default field parsing mechanism
+by specifying explicit locations.
+@end itemize
+
+@item
 Support for MirBSD was removed.
 
 @item
 Support for GNU/Linux on Alpha was removed.
+
+@item
+Shell startup files are supplied with the distribution and
+installed by @samp{make install} (@pxref{Shell Startup Files}).
+
+@item
+The @command{igawk} program and its manual page are no longer
+installed when @command{gawk} is built.
+@xref{Igawk Program}.
+
 @end itemize
 
 @c XXX ADD MORE STUFF HERE
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 68f0510c..94001fac 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -36600,7 +36600,9 @@ I've tried to follow this general order, esp.@: for the 3.0 and 3.1 sections:
        new keywords
        new command-line options
        behavioral changes
-       new ports
+       extension API changes
+       new / deprecated / removed ports
+       installation time stuff
 Within each category, be alphabetical.
 @end ignore
 
@@ -37112,10 +37114,10 @@ Cray
 MIPS RiscOS
 
 @item
-MS-DOS with Microsoft Compiler
+MS-DOS with the Microsoft Compiler
 
 @item
-MS-Windows with Microsoft Compiler
+MS-Windows with the Microsoft Compiler
 
 @item
 NeXT
@@ -37200,7 +37202,7 @@ Support for Ultrix was removed.
 
 @end itemize
 
-Version 4.2 introduced the following changes:
+Version 4.2 of @command{gawk} introduced the following changes:
 
 @itemize @bullet
 @item
@@ -37209,18 +37211,26 @@ environment and that of programs that it runs.
 @xref{Auto-set}.
 
 @item
-The @code{PROCINFO["argv"} array.
+@code{FIELDWIDTHS} was enhanced to allow skipping characters
+before assigning a value to a field
+(@pxref{Splitting By Content}).
+
+@item
+The @code{PROCINFO["argv"]} array.
 @xref{Auto-set}.
 
 @item
-The @option{--pretty-print} option no longer runs the @command{awk}
-program too.
-@xref{Options}.
+The maximum number of hexadecimal digits in @samp{\x} escapes
+is now two.
+@xref{Escape Sequences}.
 
 @item
-The @command{igawk} program and its manual page are no longer
-installed when @command{gawk} is built.
-@xref{Igawk Program}.
+Strongly typed regexp constants of the form @samp{@@/@dots{}/}
+(@pxref{Strong Regexp Constants}).
+
+@item
+The bitwise functions changed, making negative arguments into
+a fatal error (@pxref{Bitwise Functions}).
 
 @ifset INTDIV
 @item
@@ -37229,13 +37239,16 @@ The @code{intdiv0()} function.
 @end ifset
 
 @item
-The maximum number of hexadecimal digits in @samp{\x} escapes
-is now two.
-@xref{Escape Sequences}.
+The @code{mktime()} function now accepts an optional
+second argument
+(@pxref{Time Functions}).
 
 @item
-Nonfatal output with @code{print} and @code{printf}.
-@xref{Nonfatal}.
+The @code{typeof()} function (@pxref{Type Functions}).
+
+@item
+Optimizations are enabled by default. Use @option{-s} /
+@option{--no-optimize} to disable optimizations.
 
 @item
 For many years, POSIX specified that default field splitting
@@ -37246,10 +37259,66 @@ field splitting with @option{--posix} also allows newlines to
 separate fields.
 
 @item
+Nonfatal output with @code{print} and @code{printf}.
+@xref{Nonfatal}.
+
+@item
+Retryable I/O via @code{PROCINFO[@var{input-file}, "RETRY"]};
+(@pxref{Retrying Input}).
+
+@item
+Changes to the pretty-printer (@pxref{Profiling}):
+
+@c nested table
+@itemize @value{MINUS}
+@item
+The @option{--pretty-print} option no longer runs the @command{awk}
+program too.
+
+@item
+Comments in the source program are preserved and placed into the
+output file.
+
+@item
+Explicit parentheses for expressions
+in the input are preserved in the generated output.
+@end itemize
+
+@item
+Improvements to the extension API
+(@pxref{Dynamic Extensions}):
+
+@c nested
+@itemize @value{MINUS}
+@item
+The @code{get_file()} function to access open redirections.
+
+@item
+The @code{nonfatal()} function for generating nonfatal error messages.
+
+@item
+Support for GMP and MPFR values.
+
+@item
+Input parsers can now override the default field parsing mechanism
+by specifying explicit locations.
+@end itemize
+
+@item
 Support for MirBSD was removed.
 
 @item
 Support for GNU/Linux on Alpha was removed.
+
+@item
+Shell startup files are supplied with the distribution and
+installed by @samp{make install} (@pxref{Shell Startup Files}).
+
+@item
+The @command{igawk} program and its manual page are no longer
+installed when @command{gawk} is built.
+@xref{Igawk Program}.
+
 @end itemize
 
 @c XXX ADD MORE STUFF HERE
diff --git a/doc/wordlist b/doc/wordlist
index 97d4fb22..378c2b46 100644
--- a/doc/wordlist
+++ b/doc/wordlist
@@ -240,6 +240,7 @@ IFSOCK
 IGNORECASE
 INPLACE
 INT
+INTDIV
 IPv
 ISBLK
 ISBN
@@ -298,6 +299,7 @@ MMK
 MMS
 MP
 MPFR
+MPZ
 MSC
 MSEC
 MSG
@@ -411,6 +413,7 @@ PowerPC
 Pr
 Pre
 Preopened
+Preprocessor
 Prestandard
 Printf
 Prolog
@@ -442,6 +445,7 @@ Regex
 Regexp
 Regexps
 Reimplementing
+Retryable
 Revout
 RiscOS
 Ritchie
@@ -668,6 +672,7 @@ awkcard
 awkforai
 awkgram
 awklib
+awknum
 awkp
 awkprof
 awks
@@ -929,6 +934,7 @@ emalloc
 embeddable
 emory
 emph
+emptor
 emxomfar
 en
 encodings
@@ -1105,6 +1111,7 @@ groupsbyuser
 grp
 gst
 gsub
+guerrero
 gunzip
 gvim
 gz
@@ -1222,6 +1229,7 @@ joe
 johansen
 johnny
 joyent
+juan
 julie
 karl
 katie
@@ -1325,6 +1333,7 @@ monthname
 moore
 mortoneccc
 mpfr
+mpz
 msg
 msgfmt
 msgid
@@ -1429,6 +1438,7 @@ nr
 nroff
 nul
 num
+numfields
 nums
 nusers
 nvalue
diff --git a/doc/wordlist2 b/doc/wordlist2
index 0d2db288..9275fdbd 100644
--- a/doc/wordlist2
+++ b/doc/wordlist2
@@ -14,6 +14,7 @@ GitHub
 ISBN
 Kahrs
 Libtool
+Makefile
 PCC
 PDF
 Rebase
@@ -22,10 +23,12 @@ Repo
 SVN
 TODO
 Texinfo
+Uncomment
 UsingGit
 Workflow
 Yehezkel
 ac
+apache
 api
 arnold
 arnoldrobbins
@@ -94,6 +97,7 @@ inlineraw
 insertcopying
 jpdev
 kbd
+labelled
 libtool
 lineannotation
 linkcolor
@@ -102,6 +106,7 @@ literallayout
 llvm
 ltu
 ludd
+maintainer's
 makeinfo
 mpfr
 multiplestates
@@ -127,6 +132,7 @@ regexp
 repo
 repo's
 samp
+savannah
 scm
 se
 setchapternewpage
@@ -152,6 +158,7 @@ texi
 texinfo
 thischapter
 thispage
+tinycc
 titlepage
 tmp
 toto