add verbose stack display option, -Dvs

[p5sagit/p5-mst-13.2.git] / pod / perlrun.pod

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 60c7929..3c1f159 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -309,6 +309,7 @@ B<-D14> is equivalent to B<-Dtls>):
 
         1  p  Tokenizing and parsing
         2  s  Stack snapshots
+                with v, displays all stacks
         4  l  Context (loop) stack processing
         8  t  Trace execution
        16  o  Method and overloading resolution
@@ -327,6 +328,7 @@ B<-D14> is equivalent to B<-Dtls>):
    131072  T  Tokenising
    262144  R  Include reference counts of dumped variables (eg when using -Ds)
    524288  J  Do not s,t,P-debug (Jump over) opcodes within package DB
+  1048576  v  Verbose: use in conjunction with other flags
 
 All these flags require B<-DDEBUGGING> when you compile the Perl
 executable (but see L<Devel::Peek>, L<re> which may change this).
@@ -909,19 +911,21 @@ C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
 
 =item :raw
 
-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>.)
+Applying the <:raw> layer is equivalent to calling C<binmode($fh)>.
+It makes the stream pass each byte as-is without any translation.
+In particular CRLF translation, and/or :utf8 inuited from locale
+are disabled.
 
-Not really useful in PERLIO environment variable, instead just use C<:unix>
-layer explicitly.
+Arranges for all accesses go straight to the lowest buffered layer provided
+by the configration. That is it strips off any layers above that layer.
 
-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 (previously sometimes also
+referred to as a "discipline") is documented as the inverse of the
+C<:crlf> layer. That is no longer the case - other layers which would
+alter binary nature of the stream are also disabled.  If you want UNIX
+line endings on a platform that normally does CRLF translation, but still
+want UTF-8 or encoding defaults the appropriate thing to do is to add
+C<:perlio> to PERLIO environment variable.
 
 =item :stdio
 
@@ -948,7 +952,7 @@ default. (To turn off that behaviour use C<:bytes> layer.)
 
 =item :win32
 
-On Win32 platfroms this I<experimental> layer uses native "handle" IO
+On Win32 platforms this I<experimental> layer uses native "handle" IO
 rather than unix-like numeric file descriptor layer. Known to be
 buggy in this release.
 
@@ -956,7 +960,7 @@ buggy in this release.
 
 On all platforms the default set of layers should give acceptable results.
 
-For UNIX platfroms that will equivalent of "unix perlio" or "stdio".
+For UNIX platforms that will equivalent of "unix perlio" or "stdio".
 Configure is setup to prefer "stdio" implementation if system's library
 provides for fast access to the buffer, otherwise it uses the "unix perlio"
 implementation.