This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
more tweaks to 'do's pod
authorDavid Mitchell <davem@iabyn.com>
Mon, 10 Apr 2017 11:43:02 +0000 (12:43 +0100)
committerDavid Mitchell <davem@iabyn.com>
Thu, 13 Apr 2017 08:58:00 +0000 (09:58 +0100)
Make it clear that both ./ and ../ are special-cased.

pod/perlfunc.pod

index c8140d5..38747a6 100644 (file)
@@ -1807,11 +1807,14 @@ X<do>
 Uses the value of EXPR as a filename and executes the contents of the
 file as a Perl script:
 
-    do './stat.pl';    # file located relative to the current dir
-    do '/foo/stat.pl'; # file located at the specified absolute path
+    # load the exact specified file (./ and ../ special-cased)
+    do '/foo/stat.pl';
+    do './stat.pl';
+    do '../foo/stat.pl';
 
-    do 'stat.pl';      # file searched for within @INC
-    do 'foo/stat.pl';  # file searched for within @INC
+    # search for the named file within @INC
+    do 'stat.pl';
+    do 'foo/stat.pl';
 
 C<do './stat.pl'> is largely like
 
@@ -1824,9 +1827,9 @@ scope; C<eval STRING> does.  It's the same, however, in that it does
 reparse the file every time you call it, so you probably don't want
 to do this inside a loop.
 
-Using C<do> with no path, like
+Using C<do> with a relative path (except for F<./> and F<../>), like
 
-    do 'stat.pl';
+    do 'foo/stat.pl';
 
 will search the L<C<@INC>|perlvar/@INC> directories, and update
 L<C<%INC>|perlvar/%INC> if the file is found.  See L<perlvar/@INC>
@@ -1855,7 +1858,8 @@ if there's a problem.
 You might like to use L<C<do>|/do EXPR> to read in a program
 configuration file.  Manual error checking can be done this way:
 
-    # read in config files: system first, then user
+    # Read in config files: system first, then user.
+    # Beware of using relative pathnames here.
     for $file ("/share/prog/defaults.rc",
                "$ENV{HOME}/.someprogrc")
     {