(perl #127380) Update PERLIO_DEBUG documentation.

Now defaults to stderr if unspecified, and requires -Di (and thus
-DDEBUGGING).

TonyC: modify a couple of verbatim lines to bring them under the limit
enforced by the new podcheck.t changes

Author: craigberry

pod/perlapio.pod

@@ -499,23 +499,25 @@ debugging.  No return value. Its main use is inside PerlIO where using
 real printf, warn() etc. would recursively call PerlIO and be a
 problem.
 
-PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical
+PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} or defaults
+to stderr if the environment variable is not defined. Typical
 use might be
 
   Bourne shells (sh, ksh, bash, zsh, ash, ...):
-   PERLIO_DEBUG=/dev/tty ./perl somescript some args
+   PERLIO_DEBUG=/tmp/perliodebug.log ./perl -Di somescript some args
 
   Csh/Tcsh:
-   setenv PERLIO_DEBUG /dev/tty
-   ./perl somescript some args
+   setenv PERLIO_DEBUG /tmp/perliodebug.log
+   ./perl -Di somescript some args
 
   If you have the "env" utility:
-   env PERLIO_DEBUG=/dev/tty ./perl somescript some args
+   env PERLIO_DEBUG=/tmp/perliodebug.log ./perl -Di somescript args
 
   Win32:
-   set PERLIO_DEBUG=CON
-   perl somescript some args
+   set PERLIO_DEBUG=perliodebug.log
+   perl -Di somescript some args
 
-If $ENV{'PERLIO_DEBUG'} is not set PerlIO_debug() is a no-op.
+On a Perl built without C<-DDEBUGGING>, or when the C<-Di> command-line switch
+is not specified, or under taint, PerlIO_debug() is a no-op.
 
 =back

pod/perlrun.pod

@@ -1155,19 +1155,22 @@ is run in taint mode.
 =item PERLIO_DEBUG
 X<PERLIO_DEBUG>
 
-If set to the name of a file or device, certain operations of PerlIO
-subsystem will be logged to that file, which is opened in append mode.
-Typical uses are in Unix:
+If set to the name of a file or device when Perl is run with the
+B<-Di> command-line switch, the logging of certain operations of
+the PerlIO subsystem will be redirected to the specified file rather
+than going to stderr, which is the default. The file is opened in append
+mode. Typical uses are in Unix:
 
-   % env PERLIO_DEBUG=/dev/tty perl script ...
+   % env PERLIO_DEBUG=/tmp/perlio.log perl -Di script ...
 
 and under Win32, the approximately equivalent:
 
    > set PERLIO_DEBUG=CON
-   perl script ...
+   perl -Di script ...
 
-This functionality is disabled for setuid scripts and for scripts run
-with B<-T>.
+This functionality is disabled for setuid scripts, for scripts run
+with B<-T>, and for scripts run on a Perl built without C<-DDEBUGGING>
+support.
 
 =item PERLLIB
 X<PERLLIB>