Document scalarref retvals of @INC hook

Or: Reinstate documentation removed by cec0e1a713ccb.

That commit’s message says ‘Change the documentation of the return
values of @INC-hooks to match what is tested to work.’  But commit
34113e50d, which came before it, had already tested scalar refs.

In any case, this feature has been here for a long time, is well
tested, ain’t going anywhere, and hence needs to be documented.

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 1acd6f2..11d187b 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -5846,17 +5846,22 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first a reference to itself, and the
 second the name of the file to be included (e.g., "F<Foo/Bar.pm>").  The
-subroutine should return either nothing or else a list of up to three 
+subroutine should return either nothing or else a list of up to four 
 values in the following order:
 
 =over
 
 =item 1
 
-A filehandle, from which the file will be read.  
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
 
 =item 2
 
+A filehandle, from which the file will be read.  
+
+=item 3
+
 A reference to a subroutine.  If there is no filehandle (previous item),
 then this subroutine is expected to generate one line of source code per
 call, writing the line into C<$_> and returning 1, then finally at end of
@@ -5865,7 +5870,7 @@ called to act as a simple source filter, with the line as read in C<$_>.
 Again, return 1 for each valid line, and 0 after all lines have been
 returned.
 
-=item 3
+=item 4
 
 Optional state for the subroutine.  The state is passed in as C<$_[1]>.  A
 reference to the subroutine itself is passed in as C<$_[0]>.