Rephrase perlop for non-destructive substitution

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

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index bc9d9bc..1d91694 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -316,7 +316,7 @@ You can use C<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
 disable all the above Unicode features.
 
 The read-only magic variable C<${^UNICODE}> reflects the numeric value
-of this setting.  This is variable is set during Perl startup and is
+of this setting.  This variable is set during Perl startup and is
 thereafter read-only.  If you want runtime effects, use the three-arg
 open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>),
 and the C<open> pragma (see L<open>).
@@ -440,7 +440,7 @@ behaves just like B<-e>, except that it implicitly enables all
 optional features (in the main compilation unit). See L<feature>.
 
 =item B<-f>
-X<-f>
+X<-f> X<sitecustomize> X<sitecustomize.pl>
 
 Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup.
 
@@ -450,6 +450,28 @@ This is a hook that allows the sysadmin to customize how perl behaves.
 It can for instance be used to add entries to the @INC array to make perl
 find modules in non-standard locations.
 
+Perl actually inserts the following code:
+
+    BEGIN {
+        do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
+            && do "$Config{sitelib}/sitecustomize.pl";
+    }
+
+Since it is an actual C<do> (not a C<require>), F<sitecustomize.pl>
+doesn't need to return a true value. The code is run in package C<main>,
+in its own lexical scope. However, if the script dies, C<$@> will not
+be set.
+
+The value of C<$Config{sitelib}> is also determined in C code and not
+read from C<Config.pm>, which is not loaded.
+
+The code is executed B<very> early. For example, any changes made to
+C<@INC> will show up in the output of `perl -V`. Of course, C<END>
+blocks will be likewise executed very late.
+
+To determine at runtime if this capability has been compiled in your
+perl, you can check the value of C<$Config{usesitecustomize}>.
+
 =item B<-F>I<pattern>
 X<-F>
 
@@ -1280,7 +1302,7 @@ See L<perlipc/"Deferred Signals (Safe Signals)">.
 X<PERL_UNICODE>
 
 Equivalent to the B<-C> command-line switch.  Note that this is not
-a boolean variable-- setting this to C<"1"> is not the right way to
+a boolean variable. Setting this to C<"1"> is not the right way to
 "enable Unicode" (whatever that would mean).  You can use C<"0"> to
 "disable Unicode", though (or alternatively unset PERL_UNICODE in
 your shell before starting Perl).  See the description of the C<-C>