X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrun.pod;h=4b86d77b51bb0ad3b19490f8895b814ea166f7bd;hb=6aa71d6ea27a640886ba2dcf7250d1be73560df8;hp=4a4c957a50820043485969da4f7c2bb4d5f800bf;hpb=607df283d68e14cbc418e3453255082dc72ca8bb;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 4a4c957..4b86d77 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -323,6 +323,7 @@ equivalent to B<-Dtls>):
     32768  D  Cleaning up
     65536  S  Thread synchronization
    131072  T  Tokenising
+   262144  R  Include reference counts of dumped variables (eg when using -Ds)
 
 All these flags require B<-DDEBUGGING> when you compile the Perl
 executable.  See the F<INSTALL> file in the Perl source distribution 
@@ -450,8 +451,7 @@ specified in the extension then it will skip that file and continue on
 with the next one (if it exists).
 
 For a discussion of issues surrounding file permissions and B<-i>,
-see L<perlfaq5/Why does Perl let me delete read-only files?  Why
-does -i clobber protected files?  Isn't this a bug in Perl?>.
+see L<perlfaq5/Why does Perl let me delete read-only files?  Why does -i clobber protected files?  Isn't this a bug in Perl?>.
 
 You cannot use B<-i> to create directories or to strip extensions from
 files.
@@ -569,12 +569,39 @@ the implicit loop, just as in B<awk>.
 
 =item B<-P>
 
-causes your program to be run through the C preprocessor before
+B<NOTE: Use of -P is strongly discouraged because of its inherent
+problems, including poor portability.>
+
+This option causes your program to be run through the C preprocessor before
 compilation by Perl.  Because both comments and B<cpp> directives begin
 with the # character, you should avoid starting comments with any words
 recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">.
-Also, in some platforms the C preprocessor knows too much: it knows
-about the C++ -style until-end-of-line comments starting with C<"//">.
+
+If you're considering using C<-P>, you might also want to look at the
+Filter::cpp module from CPAN.
+
+The problems of -P include, but are not limited to:
+
+=over 10
+
+=item *
+
+The C<#!> line is stripped, so any switches there don't apply.
+
+=item *
+
+A C<-P> on a C<#!> line doesn't work.
+
+=item *
+
+B<All> lines that begin with (whitespace and) a C<#> but
+do not look like cpp commands, are stripped, including anything
+inside Perl strings, regular expressions, and here-docs . 
+
+=item *
+
+In some platforms the C preprocessor knows too much: it knows about
+the C++ -style until-end-of-line comments starting with C<"//">.
 This will cause problems with common Perl constructs like
 
     s/foo//;
@@ -588,6 +615,23 @@ like for example C<"!">:
 
     s!foo!!;
 
+
+
+=item *
+
+It requires not only a working C preprocessor but also a working
+F<sed>.  If not on UNIX, you are probably out of luck on this.
+
+=item *
+
+Script line numbers are not preserved.
+
+=item *
+
+The C<-x> does not work with C<-P>.
+
+=back
+
 =item B<-s>
 
 enables rudimentary switch parsing for switches on the command
@@ -830,7 +874,12 @@ after compilation.
 
 Relevant only if your perl executable was built with B<-DDEBUGGING>,
 this controls the behavior of global destruction of objects and other
-references.
+references.  See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
+
+=item PERL_ENCODING
+
+If using the C<encoding> pragma without an explicit encoding name, the
+PERL_ENCODING environment variable is consulted for an encoding name.
 
 =item PERL_ROOT (specific to the VMS port)