Update doc w.r.t. cygwin binary mode.

4 files changed, 108 insertions, 61 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a8e3368f..a1fd0c82 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2018-02-08         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Clarify binary mode is default on Cygwin,
+	improve section on using on PCs to refer to MinGW and DJGPP.
+	Thanks for the report to a contributor who wishes to
+	remain anonymous.
+
 2018-01-28         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* wordlist: Updated.
diff --git a/doc/gawk.info b/doc/gawk.info
index b2726536..8d4643ee 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -29150,8 +29150,12 @@ File: gawk.info,  Node: PC Using,  Next: Cygwin,  Prev: PC Compiling,  Up: PC In
 B.3.1.3 Using 'gawk' on PC Operating Systems
 ............................................
 
-Under MS-Windows, the Cygwin and MinGW environments support both the
-'|&' operator and TCP/IP networking (*note TCP/IP Networking::).
+Information in this section applies to the MinGW and DJGPP ports of
+'gawk'.  *Note Cygwin:: for information about the Cygwin port.
+
+   Under MS-Windows, the MinGW environment supports both the '|&'
+operator and TCP/IP networking (*note TCP/IP Networking::).  The DJGPP
+environment does not support '|&'.
 
    The MS-Windows version of 'gawk' searches for program files as
 described in *note AWKPATH Variable::.  However, semicolons (rather than
@@ -29239,6 +29243,14 @@ Cygwin is the same as for a Unix system:
 on Cygwin takes considerably longer.  However, it does finish, and then
 the 'make' proceeds as usual.
 
+   Recent versions of Cygwin open all files in binary mode.  This means
+that you should use 'RS = "\r?\n"' in order to be able to handle
+standard MS-Windows text files with carriage-return plus line-feed line
+endings.
+
+   The Cygwin environment supports both the '|&' operator and TCP/IP
+networking (*note TCP/IP Networking::).
+
 
 File: gawk.info,  Node: MSYS,  Prev: Cygwin,  Up: PC Installation
 
@@ -33022,7 +33034,7 @@ Index
 * /inet/... special files (gawk):        TCP/IP Networking.   (line   6)
 * /inet4/... special files (gawk):       TCP/IP Networking.   (line   6)
 * /inet6/... special files (gawk):       TCP/IP Networking.   (line   6)
-* ; (semicolon), AWKPATH variable and:   PC Using.            (line   9)
+* ; (semicolon), AWKPATH variable and:   PC Using.            (line  13)
 * ; (semicolon), separating statements in actions: Statements/Lines.
                                                               (line  90)
 * ; (semicolon), separating statements in actions <1>: Action Overview.
@@ -33351,7 +33363,7 @@ Index
 * awka compiler for awk:                 Other Versions.      (line  73)
 * AWKLIBPATH environment variable:       AWKLIBPATH Variable. (line   6)
 * AWKPATH environment variable:          AWKPATH Variable.    (line   6)
-* AWKPATH environment variable <1>:      PC Using.            (line   9)
+* AWKPATH environment variable <1>:      PC Using.            (line  13)
 * awkprof.out file:                      Profiling.           (line   6)
 * awksed.awk program:                    Simple Sed.          (line  25)
 * awkvars.out file:                      Options.             (line  94)
@@ -33445,7 +33457,7 @@ Index
 * bindtextdomain() function (gawk), portability and: I18N Portability.
                                                               (line  33)
 * BINMODE variable:                      User-modified.       (line  15)
-* BINMODE variable <1>:                  PC Using.            (line  16)
+* BINMODE variable <1>:                  PC Using.            (line  20)
 * bit-manipulation functions:            Bitwise Functions.   (line   6)
 * bits2str() user-defined function:      Bitwise Functions.   (line  69)
 * bitwise AND:                           Bitwise Functions.   (line  40)
@@ -33628,7 +33640,7 @@ Index
 * common extensions, /dev/stderr special file: Special FD.    (line  48)
 * common extensions, /dev/stdin special file: Special FD.     (line  48)
 * common extensions, /dev/stdout special file: Special FD.    (line  48)
-* common extensions, BINMODE variable:   PC Using.            (line  16)
+* common extensions, BINMODE variable:   PC Using.            (line  20)
 * common extensions, delete to delete entire arrays: Delete.  (line  39)
 * common extensions, func keyword:       Definition Syntax.   (line  99)
 * common extensions, length() applied to an array: String Functions.
@@ -33935,7 +33947,7 @@ Index
 * differences in awk and gawk, BINMODE variable: User-modified.
                                                               (line  15)
 * differences in awk and gawk, BINMODE variable <1>: PC Using.
-                                                              (line  16)
+                                                              (line  20)
 * differences in awk and gawk, close() function: Close Files And Pipes.
                                                               (line  81)
 * differences in awk and gawk, close() function <1>: Close Files And Pipes.
@@ -34169,7 +34181,7 @@ Index
 * extensions, common, /dev/stderr special file: Special FD.   (line  48)
 * extensions, common, /dev/stdin special file: Special FD.    (line  48)
 * extensions, common, /dev/stdout special file: Special FD.   (line  48)
-* extensions, common, BINMODE variable:  PC Using.            (line  16)
+* extensions, common, BINMODE variable:  PC Using.            (line  20)
 * 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  99)
@@ -34477,7 +34489,7 @@ Index
 * gawk, line continuation in:            Conditional Exp.     (line  34)
 * gawk, LINT variable in:                User-modified.       (line  90)
 * gawk, list of contributors to:         Contributors.        (line   6)
-* gawk, MS-Windows version of:           PC Using.            (line   9)
+* gawk, MS-Windows version of:           PC Using.            (line  13)
 * gawk, newlines in:                     Statements/Lines.    (line  12)
 * gawk, octal numbers and:               Nondecimal-numbers.  (line  41)
 * gawk, predefined variables and:        Built-in Variables.  (line  14)
@@ -35493,12 +35505,12 @@ Index
 * search and replace in strings:         String Functions.    (line  89)
 * search in string:                      String Functions.    (line 155)
 * search paths:                          Programs Exercises.  (line  70)
-* search paths <1>:                      PC Using.            (line   9)
+* search paths <1>:                      PC Using.            (line  13)
 * search paths <2>:                      VMS Running.         (line  57)
 * search paths, for loadable extensions: AWKLIBPATH Variable. (line   6)
 * search paths, for source files:        AWKPATH Variable.    (line   6)
 * search paths, for source files <1>:    Programs Exercises.  (line  70)
-* search paths, for source files <2>:    PC Using.            (line   9)
+* search paths, for source files <2>:    PC Using.            (line  13)
 * search paths, for source files <3>:    VMS Running.         (line  57)
 * searching, files for regular expressions: Egrep Program.    (line   6)
 * searching, for words:                  Dupword Program.     (line   6)
@@ -35506,7 +35518,7 @@ Index
 * sed utility <1>:                       Simple Sed.          (line   6)
 * sed utility <2>:                       Glossary.            (line  16)
 * seeding random number generator:       Numeric Functions.   (line  64)
-* semicolon (;), AWKPATH variable and:   PC Using.            (line   9)
+* semicolon (;), AWKPATH variable and:   PC Using.            (line  13)
 * semicolon (;), separating statements in actions: Statements/Lines.
                                                               (line  90)
 * semicolon (;), separating statements in actions <1>: Action Overview.
@@ -36522,52 +36534,52 @@ Node: PC Installation1174500
 Node: PC Binary Installation1175338
 Node: PC Compiling1175773
 Node: PC Using1176890
-Node: Cygwin1179935
-Node: MSYS1180705
-Node: VMS Installation1181206
-Node: VMS Compilation1181997
-Ref: VMS Compilation-Footnote-11183226
-Node: VMS Dynamic Extensions1183284
-Node: VMS Installation Details1184969
-Node: VMS Running1187222
-Node: VMS GNV1191501
-Node: VMS Old Gawk1192236
-Node: Bugs1192707
-Node: Bug address1193370
-Node: Usenet1196162
-Node: Maintainers1196939
-Node: Other Versions1198200
-Node: Installation summary1204962
-Node: Notes1206164
-Node: Compatibility Mode1207029
-Node: Additions1207811
-Node: Accessing The Source1208736
-Node: Adding Code1210173
-Node: New Ports1216392
-Node: Derived Files1220880
-Ref: Derived Files-Footnote-11226526
-Ref: Derived Files-Footnote-21226561
-Ref: Derived Files-Footnote-31227159
-Node: Future Extensions1227273
-Node: Implementation Limitations1227931
-Node: Extension Design1229114
-Node: Old Extension Problems1230268
-Ref: Old Extension Problems-Footnote-11231786
-Node: Extension New Mechanism Goals1231843
-Ref: Extension New Mechanism Goals-Footnote-11235207
-Node: Extension Other Design Decisions1235396
-Node: Extension Future Growth1237509
-Node: Old Extension Mechanism1238345
-Node: Notes summary1240108
-Node: Basic Concepts1241290
-Node: Basic High Level1241971
-Ref: figure-general-flow1242253
-Ref: figure-process-flow1242938
-Ref: Basic High Level-Footnote-11246239
-Node: Basic Data Typing1246424
-Node: Glossary1249752
-Node: Copying1281590
-Node: GNU Free Documentation License1319133
-Node: Index1344253
+Node: Cygwin1180105
+Node: MSYS1181204
+Node: VMS Installation1181705
+Node: VMS Compilation1182496
+Ref: VMS Compilation-Footnote-11183725
+Node: VMS Dynamic Extensions1183783
+Node: VMS Installation Details1185468
+Node: VMS Running1187721
+Node: VMS GNV1192000
+Node: VMS Old Gawk1192735
+Node: Bugs1193206
+Node: Bug address1193869
+Node: Usenet1196661
+Node: Maintainers1197438
+Node: Other Versions1198699
+Node: Installation summary1205461
+Node: Notes1206663
+Node: Compatibility Mode1207528
+Node: Additions1208310
+Node: Accessing The Source1209235
+Node: Adding Code1210672
+Node: New Ports1216891
+Node: Derived Files1221379
+Ref: Derived Files-Footnote-11227025
+Ref: Derived Files-Footnote-21227060
+Ref: Derived Files-Footnote-31227658
+Node: Future Extensions1227772
+Node: Implementation Limitations1228430
+Node: Extension Design1229613
+Node: Old Extension Problems1230767
+Ref: Old Extension Problems-Footnote-11232285
+Node: Extension New Mechanism Goals1232342
+Ref: Extension New Mechanism Goals-Footnote-11235706
+Node: Extension Other Design Decisions1235895
+Node: Extension Future Growth1238008
+Node: Old Extension Mechanism1238844
+Node: Notes summary1240607
+Node: Basic Concepts1241789
+Node: Basic High Level1242470
+Ref: figure-general-flow1242752
+Ref: figure-process-flow1243437
+Ref: Basic High Level-Footnote-11246738
+Node: Basic Data Typing1246923
+Node: Glossary1250251
+Node: Copying1282089
+Node: GNU Free Documentation License1319632
+Node: Index1344752
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 9b4d392e..d99e33bb 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -39745,9 +39745,14 @@ type @samp{make mingw32}.
 @cindex operating systems, PC, @command{gawk} on
 @cindex PC operating systems, @command{gawk} on
 
-Under MS-Windows, the Cygwin and MinGW environments support
+Information in this section applies to the MinGW and
+DJGPP ports of @command{gawk}. @xref{Cygwin} for information
+about the Cygwin port.
+
+Under MS-Windows, the MinGW environment supports
 both the @samp{|&} operator and TCP/IP networking
 (@pxref{TCP/IP Networking}).
+The DJGPP environment does not support @samp{|&}.
 
 @cindex search paths
 @cindex search paths, for source files
@@ -39873,6 +39878,15 @@ When compared to GNU/Linux on the same system, the @samp{configure}
 step on Cygwin takes considerably longer.  However, it does finish,
 and then the @samp{make} proceeds as usual.
 
+Recent versions of Cygwin open all files in binary mode. This means
+that you should use @samp{RS = "\r?\n"} in order to be able to
+handle standard MS-Windows text files with carriage-return plus
+line-feed line endings.
+
+The Cygwin environment supports
+both the @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking}).
+
 @node MSYS
 @appendixsubsubsec Using @command{gawk} In The MSYS Environment
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index ce7d62ca..d0317ce3 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -38719,9 +38719,14 @@ type @samp{make mingw32}.
 @cindex operating systems, PC, @command{gawk} on
 @cindex PC operating systems, @command{gawk} on
 
-Under MS-Windows, the Cygwin and MinGW environments support
+Information in this section applies to the MinGW and
+DJGPP ports of @command{gawk}. @xref{Cygwin} for information
+about the Cygwin port.
+
+Under MS-Windows, the MinGW environment supports
 both the @samp{|&} operator and TCP/IP networking
 (@pxref{TCP/IP Networking}).
+The DJGPP environment does not support @samp{|&}.
 
 @cindex search paths
 @cindex search paths, for source files
@@ -38847,6 +38852,15 @@ When compared to GNU/Linux on the same system, the @samp{configure}
 step on Cygwin takes considerably longer.  However, it does finish,
 and then the @samp{make} proceeds as usual.
 
+Recent versions of Cygwin open all files in binary mode. This means
+that you should use @samp{RS = "\r?\n"} in order to be able to
+handle standard MS-Windows text files with carriage-return plus
+line-feed line endings.
+
+The Cygwin environment supports
+both the @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking}).
+
 @node MSYS
 @appendixsubsubsec Using @command{gawk} In The MSYS Environment