Further discouraging of :raw.

p4raw-id: //depot/perl@17271

4 files changed, 41 insertions, 32 deletions

diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm
index 6bef21fe18..1ad295a5f1 100644
--- a/lib/PerlIO.pm
+++ b/lib/PerlIO.pm
@@ -33,8 +33,8 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
 
 =head1 SYNOPSIS
 
-  open($fh,">:crlf","my.txt")
-  open($fh,">:raw","his.jpg")
+  open($fh,">:crlf", "my.txt")
+  open($fh,">:bytes","his.jpg")
 
   Shell:
     PERLIO=perlio perl ....
@@ -108,6 +108,8 @@ to a such a stream.
 
 =item raw
 
+B<Note that the explicit use of the C<raw> layer is deprecated.>
+
 A pseudo-layer which performs two functions (which is messy, but
 necessary to maintain compatibility with non-PerlIO builds of Perl
 and their way things have been documented elsewhere).
diff --git a/lib/open.pm b/lib/open.pm
index aab99fb713..872d8ea56c 100644
--- a/lib/open.pm
+++ b/lib/open.pm
@@ -146,7 +146,7 @@ open - perl pragma to set default disciplines for input and output
 
 =head1 SYNOPSIS
 
-    use open IN  => ":crlf", OUT => ":raw";
+    use open IN  => ":crlf", OUT => ":bytes";
     use open OUT => ':utf8';
     use open IO  => ":encoding(iso-8859-7)";
 
@@ -263,9 +263,9 @@ Directory handles may also support disciplines in future.
 =head1 NONPERLIO FUNCTIONALITY
 
 If Perl is not built to use PerlIO as its IO system then only the two
-pseudo-disciplines ":raw" and ":crlf" are available.
+pseudo-disciplines C<:bytes> and C<:crlf> are available.
 
-The ":raw" discipline corresponds to "binary mode" and the ":crlf"
+The C<:bytes> discipline corresponds to "binary mode" and the C<:crlf>
 discipline corresponds to "text mode" on platforms that distinguish
 between the two modes when opening files (which is many DOS-like
 platforms, including Windows).  These two disciplines are no-ops on
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index f2ca525317..858f23f5ad 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -449,21 +449,25 @@ L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE
 
-Arranges for FILEHANDLE to be read or written in "binary" or "text" mode
-on systems where the run-time libraries distinguish between binary and
-text files.  If FILEHANDLE is an expression, the value is taken as the
-name of the filehandle.
-
-DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for
-"text" mode.  If the DISCIPLINE is omitted, it defaults to C<:raw>.
-Returns true on success, C<undef> on failure.  To mark FILEHANDLE as
-UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
-For backward compatibility binmode(FILEHANDLE) also implicitly
-marks the handle as bytes.
-
-The C<:raw> are C<:clrf>, and any other directives of the form
-C<:...>, are called I/O I<disciplines>.  The C<open> pragma can be
-used to establish default I/O disciplines.  See L<open>.
+Arranges for FILEHANDLE to be read or written in "binary" or "text"
+mode on systems where the run-time libraries distinguish between
+binary and text files.  If FILEHANDLE is an expression, the value is
+taken as the name of the filehandle.  Returns true on success,
+C<undef> on failure.
+
+DISCIPLINE can be either of C<:bytes> for "binary" mode or C<:crlf>
+for "text" mode.  If the DISCIPLINE is omitted, it defaults to
+C<:bytes>.  To mark FILEHANDLE as UTF-8, use C<:utf8>.  For backward
+compatibility C<binmode(FILEHANDLE)> also implicitly marks the
+filehandle as bytes.
+
+The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
+form C<:...>, are called I/O I<disciplines>.  The C<open> pragma can
+be used to establish default I/O disciplines.  See L<open>.
+
+The C<:raw> discipline is deprecated.  (As opposed to what Camel III
+said, it is not the inverse of C<:crlf>.)  See L<perlrun> and the
+discussion about the PERLIO environment variable.
 
 In general, binmode() should be called after open() but before any I/O
 is done on the filehandle.  Calling binmode() will flush any possibly
@@ -473,12 +477,13 @@ the default character encoding of the handle, see L<open>.
 The C<:encoding> discipline sometimes needs to be called in
 mid-stream, and it doesn't flush the stream.
 
-On some systems binmode() is necessary when you're not working with a
-text file.  For the sake of portability it is a good idea to always use
-it when appropriate, and to never use it when it isn't appropriate.
+On some systems (in general, DOS and Windows-based systems) binmode()
+is necessary when you're not working with a text file.  For the sake
+of portability it is a good idea to always use it when appropriate,
+and to never use it when it isn't appropriate.
 
-In other words:  Regardless of platform, use binmode() on binary
-files, and do not use binmode() on text files.
+In other words: regardless of platform, use binmode() on binary files
+(like for example images), and do not use binmode() on text files.
 
 The operating system, device drivers, C libraries, and Perl run-time
 system all work together to let the programmer treat a single
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 60c7929566..2531838995 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -909,19 +909,21 @@ C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
 
 =item :raw
 
+B<Note that the explicit use of the C<:raw> layer is deprecated.>
+
 Arranges for all accesses go straight to the lowest level layer provided
 by the configration. That is it strips off any layers above that layer.
 (The intent - unless layers are then pushed on top again -
 is to make perl's C<read> behave like C<sysread>.)
 
-Not really useful in PERLIO environment variable, instead just use C<:unix>
-layer explicitly.
+Not really useful in PERLIO environment variable, instead just use
+C<:unix> layer explicitly.
 
-In perl5.6 and some books the C<:raw> layer (also called a discipline) is
-documented as the inverse of the C<:crlf> layer. That is not really the case.
-If you want UNIX line endings on a platform that normaly does CRLF translation
-the appropriate thing to do is to add C<:perlio> to PERLIO environment
-variable.
+In Perl 5.6 and some books the C<:raw> layer (also called a discipline)
+is documented as the inverse of the C<:crlf> layer. That is not really
+the case.  If you want UNIX line endings on a platform that normally
+does CRLF translation the appropriate thing to do is to add C<:perlio>
+to PERLIO environment variable.
 
 =item :stdio