Make (hopefully) the Windows CR CR LF bug go away

by making the CRLF layer repel any other CRLF layers.
In other words: binmode(FH, ":crlf") in e.g. Win32
is effectively a no-op since there already is one
CRLF layer in the stack by default.

p4raw-id: //depot/perl@20674

1 files changed, 17 insertions, 3 deletions

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index d8ed107ac7..3ddb2f8f68 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -947,9 +947,23 @@ You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
 
 =item :crlf
 
-A layer that implements DOS/Windows like CRLF line endings.
-On read converts pairs of CR,LF to a single "\n" newline character.
-On write converts each "\n" to a CR,LF pair.
+A layer that implements DOS/Windows like CRLF line endings.  On read
+converts pairs of CR,LF to a single "\n" newline character.  On write
+converts each "\n" to a CR,LF pair.  Note that this layer likes to be
+one of its kind: it silently ignores attempts to be pushed into the
+layer stack more than once.
+
+(Gory details follow) To be more exact what happens is this: after
+pushing itself to the stack, the C<:crlf> layer checks all the layers
+below itself to find the first layer that is capable of being a CRLF
+layer but is not yet enabled to be a CRLF layer.  If it finds such a
+layer, it enables the CRLFness of that other deeper layer, and then
+pops itself off the stack.  If not, fine, use the one we just pushed.
+
+The end result is that a C<:crlf> means "please enable the first CRLF
+layer you can find, and if you can't find one, here would be a good
+spot to place a new one."
+
 Based on the C<:perlio> layer.
 
 =item :mmap