This is patch.2b1g to perl5.002beta1.

cd to your perl source directory, and type
	patch -p1 -N < patch.2b1g

This patch is just my packaging of Tom's documentation patches
he released as patch.2b1g.

Patch and enjoy,

    Andy Dougherty		doughera@lafcol.lafayette.edu
    Dept. of Physics
    Lafayette College, Easton PA 18042

1 files changed, 606 insertions, 52 deletions

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 1f5201a4c7..a893ff5478 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -6,8 +6,11 @@ perlsub - Perl subroutines
 
 To declare subroutines:
 
-    sub NAME;	   # A "forward" declaration.
-    sub NAME BLOCK # A declaration and a definition.
+    sub NAME;	      	  # A "forward" declaration.
+    sub NAME(PROTO);  	  #  ditto, but with prototypes
+
+    sub NAME BLOCK    	  # A declaration and a definition.
+    sub NAME(PROTO) BLOCK #  ditto, but with prototypes
 
 To define an anonymous subroutine at runtime:
 
@@ -19,42 +22,56 @@ To import subroutines:
 
 To call subroutines:
 
-    &NAME	   # Passes current @_ to subroutine.
-    &NAME(LIST);   # Parens required with & form.
     NAME(LIST);	   # & is optional with parens.
     NAME LIST;	   # Parens optional if predeclared/imported.
+    &NAME;	   # Passes current @_ to subroutine.
 
 =head1 DESCRIPTION
 
-Any arguments passed to the routine come in as array @_, that is
-($_[0], $_[1], ...).  The array @_ is a local array, but its values are
-references to the actual scalar parameters.  The return value of the
-subroutine is the value of the last expression evaluated, and can be
-either an array value or a scalar value.  Alternatively, a return
-statement may be used to specify the returned value and exit the
-subroutine.  To create local variables see the local() and my()
-operators.
-
-A subroutine may be called using the "&" prefix.  The "&" is optional in Perl
-5, and so are the parens if the subroutine has been predeclared.
-(Note, however, that the "&" is I<NOT> optional when you're just naming the
-subroutine, such as when it's used as an argument to defined() or
-undef().  Nor is it optional when you want to do an indirect subroutine
-call with a subroutine name or reference using the C<&$subref()> or
-C<&{$subref}()> constructs.  See L<perlref> for more on that.)
+Like many languages, Perl provides for user-defined subroutines.  These
+may be located anywhere in the main program, loaded in from other files
+via the C<do>, C<require>, or C<use> keywords, or even generated on the
+fly using C<eval> or anonymous subroutines (closures).  You can even call
+a function indirectly using a variable containing its name or a CODE reference.
+
+The Perl model for function call and return values is simple: all
+functions are passed as parameters one single flat list of scalars, and
+all functions likewise return to their caller one single flat list of
+scalars.  Any arrays or hashes in these call and return lists will
+collapse, losing their identities--but you may always use
+pass-by-reference instead to avoid this.  Both call and return lists may
+contain as many or as few scalar elements as you'd like.  (Often a
+function without an explicit return statement is called a subroutine, but
+there's really no difference from the language's perspective.)
+
+Any arguments passed to the routine come in as the array @_.  Thus if you
+called a function with two arguments, those would be stored in C<$_[0]>
+and C<$_[1]>.  The array @_ is a local array, but its values are implicit
+references (predating L<perlref>) to the actual scalar parameters.  The
+return value of the subroutine is the value of the last expression
+evaluated.  Alternatively, a return statement may be used to specify the
+returned value and exit the subroutine.  If you return one or more arrays
+and/or hashes, these will be flattened together into one large
+indistinguishable list.
+
+Perl does not have named formal parameters, but in practice all you do is
+assign to a my() list of these.  Any variables you use in the function
+that aren't declared private are global variables.  For the gory details
+on creating private variables, see the sections below on L<"Private
+Variables via my()"> and L</"Temporary Values via local()">.  To create
+protected environments for a set of functions in a separate package (and
+probably a separate file), see L<perlmod/"Packages">.
 
 Example:
 
-    sub MAX {
-	my $max = pop(@_);
+    sub max {
+	my $max = shift(@_);
 	foreach $foo (@_) {
 	    $max = $foo if $max < $foo;
 	}
-	$max;
+	return $max;
     }
-
-    ...
-    $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
+    $bestday = max($mon,$tue,$wed,$thu,$fri);
 
 Example:
 
@@ -62,7 +79,7 @@ Example:
     #  that start with whitespace
 
     sub get_line {
-	$thisline = $lookahead;
+	$thisline = $lookahead;  # GLOBAL VARIABLES!!
 	LINE: while ($lookahead = <STDIN>) {
 	    if ($lookahead =~ /^[ \t]/) {
 		$thisline .= $lookahead;
@@ -83,44 +100,321 @@ Use array assignment to a local list to name your formal arguments:
 
     sub maybeset {
 	my($key, $value) = @_;
-	$foo{$key} = $value unless $foo{$key};
+	$Foo{$key} = $value unless $Foo{$key};
     }
 
-This also has the effect of turning call-by-reference into
-call-by-value, since the assignment copies the values.
+This also has the effect of turning call-by-reference into call-by-value,
+since the assignment copies the values.  Otherwise a function is free to
+do in-place modifications of @_ and change its callers values.
+
+    upcase_in($v1, $v2);  # this changes $v1 and $v2
+    sub upcase_in {
+	for (@_) { tr/a-z/A-Z/ } 
+    } 
+
+You aren't allowed to modify constants in this way, of course.  If an
+argument were actually literal and you tried to change it, you'd take a
+(presumably fatal) exception.   For example, this won't work:
+
+    upcase_in("frederick");
+
+It would be much safer if the upcase_in() function 
+were written to return a copy of its parameters instead
+of changing them in place:
+
+    ($v3, $v4) = upcase($v1, $v2);  # this doesn't
+    sub upcase {
+	my @parms = @_;
+	for (@parms) { tr/a-z/A-Z/ } 
+	return @parms;
+    } 
+
+Notice how this (unprototyped) function doesn't care whether it was passed
+real scalars or arrays.  Perl will see everything as one big long flat @_
+parameter list.  This is one of the ways where Perl's simple
+argument-passing style shines.  The upcase() function would work perfectly
+well without changing the upcase() definition even if we fed it things
+like this:
+
+    @newlist   = upcase(@list1, @list2);
+    @newlist   = upcase( split /:/, $var );
+
+Do not, however, be tempted to do this:
+
+    (@a, @b)   = upcase(@list1, @list2);
+
+Because like its flat incoming parameter list, the return list is also
+flat.  So all you have managed to do here is stored everything in @a and
+made @b an empty list.  See L</"Pass by Reference"> for alternatives.
+
+A subroutine may be called using the "&" prefix.  The "&" is optional in
+Perl 5, and so are the parens if the subroutine has been predeclared.
+(Note, however, that the "&" is I<NOT> optional when you're just naming
+the subroutine, such as when it's used as an argument to defined() or
+undef().  Nor is it optional when you want to do an indirect subroutine
+call with a subroutine name or reference using the C<&$subref()> or
+C<&{$subref}()> constructs.  See L<perlref> for more on that.)
 
 Subroutines may be called recursively.  If a subroutine is called using
-the "&" form, the argument list is optional.  If omitted, no @_ array is
-set up for the subroutine; the @_ array at the time of the call is
-visible to subroutine instead.
+the "&" form, the argument list is optional, and if omitted, no @_ array is
+set up for the subroutine: the @_ array at the time of the call is
+visible to subroutine instead.  This is an efficiency mechanism that
+new users may wish to avoid.
 
     &foo(1,2,3);	# pass three arguments
     foo(1,2,3);		# the same
 
     foo();		# pass a null list
     &foo();		# the same
-    &foo;		# pass no arguments--more efficient
 
-If a module wants to create a private subroutine that cannot be called
-from outside the module, it can declare a lexical variable containing
-an anonymous sub reference:
+    &foo;		# foo() get current args, like foo(@_) !!
+    foo;		# like foo() IFF sub foo pre-declared, else "foo"
+
+=head2 Private Variables via my()
+
+Synopsis:
+
+    my $foo;	    	# declare $foo lexically local
+    my (@wid, %get); 	# declare list of variables local
+    my $foo = "flurp";	# declare $foo lexical, and init it
+    my @oof = @bar;	# declare @oof lexical, and init it
+
+A "my" declares the listed variables to be confined (lexically) to the
+enclosing block, subroutine, C<eval>, or C<do/require/use>'d file.  If
+more than one value is listed, the list must be placed in parens.  All
+listed elements must be legal lvalues.  Only alphanumeric identifiers may
+be lexically scoped--magical builtins like $/ must currently be localized with
+"local" instead.  
+
+Unlike dynamic variables created by the "local" statement, lexical
+variables declared with "my" are totally hidden from the outside world,
+including any called subroutines (even if it's the same subroutine called
+from itself or elsewhere--every call gets its own copy).
+
+(An eval(), however, can see the lexical variables of the scope it is
+being evaluated in so long as the names aren't hidden by declarations within
+the eval() itself.  See L<perlref>.)
+
+The parameter list to my() may be assigned to if desired, which allows you
+to initialize your variables.  (If no initializer is given for a
+particular variable, it is created with the undefined value.)  Commonly
+this is used to name the parameters to a subroutine.  Examples:
+
+    $arg = "fred";	  # "global" variable
+    $n = cube_root(27);
+    print "$arg thinks the root is $n\n";
+ fred thinks the root is 3
+
+    sub cube_root {
+	my $arg = shift;  # name doesn't matter
+	$arg **= 1/3;
+	return $arg;
+    } 			
+
+The "my" is simply a modifier on something you might assign to.  So when
+you do assign to the variables in its argument list, the "my" doesn't
+change whether those variables is viewed as a scalar or an array.  So
+
+    my ($foo) = <STDIN>;
+    my @FOO = <STDIN>;
+
+both supply a list context to the righthand side, while
+
+    my $foo = <STDIN>;
+
+supplies a scalar context.  But the following only declares one variable:
 
-    my $subref = sub { ... }
-    &$subref(1,2,3);
+    my $foo, $bar = 1;
 
-As long as the reference is never returned by any function within the module,
-no outside module can see the subroutine, since its name is not in any
-package's symbol table.
+That has the same effect as
 
-=head2 Passing Symbol Table Entries
+    my $foo;
+    $bar = 1;
 
-[Note:  The mechanism described in this section works fine in Perl 5, but
-the new reference mechanism is generally easier to work with.  See L<perlref>.]
+The declared variable is not introduced (is not visible) until after
+the current statement.  Thus,
+
+    my $x = $x;
+
+can be used to initialize the new $x with the value of the old $x, and 
+the expression
+
+    my $x = 123 and $x == 123
+
+is false unless the old $x happened to have the value 123.
+
+Some users may wish to encourage the use of lexically scoped variables.
+As an aid to catching implicit references to package variables,
+if you say
+
+    use strict 'vars';
+
+then any variable reference from there to the end of the enclosing
+block must either refer to a lexical variable, or must be fully
+qualified with the package name.  A compilation error results
+otherwise.  An inner block may countermand this with S<"no strict 'vars'">.
+
+A my() has both a compile-time and a run-time effect.  At compile time,
+the compiler takes notice of it; the principle usefulness of this is to
+quiet C<use strict 'vars'>.  The actual initialization doesn't happen
+until run time, so gets executed every time through a loop.
+
+Variables declared with "my" are not part of any package and are therefore
+never fully qualified with the package name.  In particular, you're not
+allowed to try to make a package variable (or other global) lexical:
+
+    my $pack::var;	# ERROR!  Illegal syntax
+    my $_;		# also illegal (currently)
+
+In fact, a dynamic variable (also known as package or global variables)
+are still accessible using the fully qualified :: notation even while a
+lexical of the same name is also visible:
+
+    package main;
+    local $x = 10;
+    my    $x = 20;
+    print "$x and $::x\n";
+
+That will print out 20 and 10.
+
+You may declare "my" variables at the outer most scope of a file to
+totally hide any such identifiers from the outside world.  This is similar
+to a C's static variables at the file level.  To do this with a subroutine
+requires the use of a closure (anonymous function).  If a block (such as
+an eval(), function, or C<package>) wants to create a private subroutine
+that cannot be called from outside that block, it can declare a lexical
+variable containing an anonymous sub reference:
+
+    my $secret_version = '1.001-beta';
+    my $secret_sub = sub { print $secret_version };
+    &$secret_sub();
+
+As long as the reference is never returned by any function within the
+module, no outside module can see the subroutine, since its name is not in
+any package's symbol table.  Remember that it's not I<REALLY> called
+$some_pack::secret_version or anything; it's just $secret_version,
+unqualified and unqualifiable.
+
+This does not work with object methods, however; all object methods have
+to be in the symbol table of some package to be found.
+
+Just because the lexical variable is lexically (also called statically)
+scoped doesn't mean that within a function it works like a C static.  It
+normally works more like a C auto.  But here's a mechanism for giving a
+function private variables with both lexical scoping and a static
+lifetime.  If you do want to create something like C's static variables,
+just enclose the whole function in an extra block, and put the
+static variable outside the function but in the block.
+
+    {
+	my $secret_val = 0; 
+	sub gimme_another {
+	    return ++$secret_val;
+	} 
+    } 
+    # $secret_val now becomes unreachable by the outside
+    # world, but retains its value between calls to gimme_another
+
+If this function is being sourced in from a separate file 
+via C<require> or C<use>, then this is probably just fine.  If it's
+all in the main program, you'll need to arrange for the my() 
+to be executed early, either by putting the whole block above
+your pain program, or more likely, merely placing a BEGIN 
+sub around it to make sure it gets executed before your program
+starts to run:
+
+    sub BEGIN {
+	my $secret_val = 0; 
+	sub gimme_another {
+	    return ++$secret_val;
+	} 
+    } 
+
+See L<perlrun> about the BEGIN function.
+
+=head2 Temporary Values via local()
+
+B<NOTE>: In general, you should be using "my" instead of "local", because
+it's faster and safer.  Execeptions to this include the global punctuation
+variables, filehandles and formats, and direct manipulation of the Perl
+symbol table itself.  Format variables often use "local" though, as do
+other variables whose current value must be visible to called
+subroutines.
+
+Synopsis:
+
+    local $foo;	    		# declare $foo dynamically local
+    local (@wid, %get); 	# declare list of variables local
+    local $foo = "flurp";	# declare $foo dynamic, and init it
+    local @oof = @bar;		# declare @oof dynamic, and init it
+
+    local *FH;			# localize $FH, @FH, %FH, &FH  ...
+    local *merlyn = *randal;	# now $merlyn is really $randal, plus
+                                #     @merlyn is really @randal, etc
+    local *merlyn = 'randal';	# SAME THING: promote 'randal' to *randal
+    local *merlyn = \$randal;   # just alias $merlyn, not @merlyn etc 
+
+A local() modifies its listed variables to be local to the enclosing
+block, (or subroutine, C<eval{}> or C<do>) and I<the any called from
+within that block>.  A local() just gives temporary values to global
+(meaning package) variables.  This is known as dynamic scoping.  Lexical
+scoping is done with "my", which works more like C's auto declarations.
+
+If more than one variable is given to local(), they must be placed in
+parens.  All listed elements must be legal lvalues.  This operator works
+by saving the current values of those variables in its argument list on a
+hidden stack and restoring them upon exiting the block, subroutine or
+eval.  This means that called subroutines can also reference the local
+variable, but not the global one.  The argument list may be assigned to if
+desired, which allows you to initialize your local variables.  (If no
+initializer is given for a particular variable, it is created with an
+undefined value.)  Commonly this is used to name the parameters to a
+subroutine.  Examples:
+
+    for $i ( 0 .. 9 ) {
+	$digits{$i} = $i;
+    } 
+    # assume this function uses global %digits hash
+    parse_num();  
+
+    # now temporarily add to %digits hash
+    if ($base12) {
+	# (NOTE: not claiming this is efficient!)
+	local %digits  = (%digits, 't' => 10, 'e' => 11);
+	parse_num();  # parse_num gets this new %digits!
+    }
+    # old %digits restored here
+
+Because local() is a run-time command, and so gets executed every time
+through a loop.  In releases of Perl previous to 5.0, this used more stack
+storage each time until the loop was exited.  Perl now reclaims the space
+each time through, but it's still more efficient to declare your variables
+outside the loop.
+
+A local is simply a modifier on an lvalue expression.  When you assign to
+a localized variable, the local doesn't change whether its list is viewed
+as a scalar or an array.  So
+
+    local($foo) = <STDIN>;
+    local @FOO = <STDIN>;
+
+both supply a list context to the righthand side, while
+
+    local $foo = <STDIN>;
+
+supplies a scalar context.
+
+=head2 Passing Symbol Table Entries (typeglobs)
+
+[Note:  The mechanism described in this section was originally the only
+way to simulate pass-by-reference in older versions of Perl.  While it
+still works fine in modern versions, the new reference mechanism is
+generally easier to work with.  See below.]
 
 Sometimes you don't want to pass the value of an array to a subroutine
 but rather the name of it, so that the subroutine can modify the global
 copy of it rather than working with a local copy.  In perl you can
-refer to all the objects of a particular name by prefixing the name
+refer to all objects of a particular name by prefixing the name
 with a star: C<*foo>.  This is often known as a "type glob", since the
 star on the front can be thought of as a wildcard match for all the
 funny prefix characters on variables and subroutines and such.
@@ -149,9 +443,242 @@ an array.  It will certainly be faster to pass the typeglob (or reference).
 Even if you don't want to modify an array, this mechanism is useful for
 passing multiple arrays in a single LIST, since normally the LIST
 mechanism will merge all the array values so that you can't extract out
-the individual arrays.
+the individual arrays.  For more on typeglobs, see L<perldata/"Typeglobs">.
+
+=head2 Pass by Reference
+
+If you want to pass more than one array or hash into a function--or 
+return them from it--and have them maintain their integrity,
+then you're going to have to use an explicit pass-by-reference.
+Before you do that, you need to understand references; see L<perlref>.
+
+Here are a few simple examples.  First, let's pass in several
+arrays to a function and have it pop all of then, return a new
+list of all their former last elements:
+
+    @tailings = popmany ( \@a, \@b, \@c, \@d );
+
+    sub popmany {
+	my $aref;
+	my @retlist = ();
+	foreach $aref ( @_ ) {
+	    push @retlist, pop @$aref;
+	} 
+	return @retlist;
+    } 
+
+Here's how you might write a function that returns a 
+list of keys occurring in all the hashes passed to it:
+
+    @common = inter( \%foo, \%bar, \%joe ); 
+    sub inter {
+	my ($k, $href, %seen); # locals
+	foreach $href (@_) {
+	    while ( $k = each %$href ) {
+		$seen{$k}++;
+	    } 
+	} 
+	return grep { $seen{$_} == @_ } keys %seen;
+    } 
+
+So far, we're just using the normal list return mechanism.
+What happens if you want to pass or return a hash?  Well, 
+if you're only using one of them, or you don't mind them 
+concatenating, then the normal calling convention is ok, although
+a little expensive.  
+
+Where people get into trouble is here:
+
+    (@a, @b) = func(@c, @d);
+or
+    (%a, %b) = func(%c, %d);
+
+That syntax simply won't work.  It just sets @a or %a and clears the @b or
+%b.  Plus the function didn't get passed into two separate arrays or
+hashes: it got one long list in @_, as always.
+
+If you can arrange for everyone to deal with this through references, it's
+cleaner code, although not so nice to look at.  Here's a function that
+takes two array references as arguments, returning the two array elements
+in order of how many elements they have in them:
+
+    ($aref, $bref) = func(\@c, \@d);
+    print "@$aref has more than @$bref\n";
+    sub func {
+	my ($cref, $dref) = @_;
+	if (@$cref > @$dref) {
+	    return ($cref, $dref);
+	} else {
+	    return ($cref, $cref);
+	} 
+    } 
+
+It turns out that you can actually do this also:
+
+    (*a, *b) = func(\@c, \@d);
+    print "@a has more than @b\n";
+    sub func {
+	local (*c, *d) = @_;
+	if (@c > @d) {
+	    return (\@c, \@d);
+	} else {
+	    return (\@d, \@c);
+	} 
+    } 
+
+Here we're using the typeglobs to do symbol table aliasing.  It's
+a tad subtle, though, and also won't work if you're using my()
+variables, since only globals (well, and local()s) are in the symbol table.
+
+If you're passing around filehandles, you could usually just use the bare
+typeglob, like *STDOUT, but typeglobs references would be better because
+they'll still work properly under C<use strict 'refs'>.  For example:
+
+    splutter(\*STDOUT);
+    sub splutter {
+	my $fh = shift;
+	print $fh "her um well a hmmm\n";
+    }
+
+    $rec = get_rec(\*STDIN);
+    sub get_rec {
+	my $fh = shift;
+	return scalar <$fh>;
+    }
+
+If you're planning on generating new filehandles, you could do this:
+
+    sub openit {
+	my $name = shift;
+	local *FH;
+	return open (FH, $path) ? \*FH : undef;
+    } 
+
+Although that will actually produce a small memory leak.  See the bottom
+of L<perlfunc/open()> for a somewhat cleaner way using the FileHandle
+functions supplied with the POSIX package.
+
+=head2 Prototypes
+
+As of the 5.002 release of perl, if you declare
+
+    sub mypush (\@@)
+
+then mypush() takes arguments exactly like push() does.  (This only works
+for function calls that are visible at compile time, not indirect function
+calls through a C<&$func> reference nor for method calls as described in
+L<perlobj>.)
+
+Here are the prototypes for some other functions that parse almost exactly
+like the corresponding builtins.
+
+    Declared as			Called as
+
+    sub mylink ($$)		mylink $old, $new
+    sub myvec ($$$)		myvec $var, $offset, 1
+    sub myindex ($$;$)		myindex &getstring, "substr"
+    sub mysyswrite ($$$;$)	mysyswrite $buf, 0, length($buf) - $off, $off
+    sub myreverse (@)		myreverse $a,$b,$c
+    sub myjoin ($@)		myjoin ":",$a,$b,$c
+    sub mypop (\@)		mypop @array
+    sub mysplice (\@$$@)	mysplice @array,@array,0,@pushme
+    sub mykeys (\%)		mykeys %{$hashref}
+    sub myopen (*;$)		myopen HANDLE, $name
+    sub mypipe (**)		mypipe READHANDLE, WRITEHANDLE
+    sub mygrep (&@)		mygrep { /foo/ } $a,$b,$c
+    sub myrand ($)		myrand 42
+    sub mytime ()		mytime
+
+Any backslashed prototype character must be passed something starting
+with that character.  Any unbackslashed @ or % eats all the rest of the
+arguments, and forces list context.  An argument represented by $
+forces scalar context.  An & requires an anonymous subroutine, and *
+does whatever it has to do to turn the argument into a reference to a
+symbol table entry.  A semicolon separates mandatory arguments from
+optional arguments.
+
+Note that the last three are syntactically distinguished by the lexer.
+mygrep() is parsed as a true list operator, myrand() is parsed as a
+true unary operator with unary precedence the same as rand(), and
+mytime() is truly argumentless, just like time().  That is, if you
+say
+
+    mytime +2;
+
+you'll get mytime() + 2, not mytime(2), which is how it would be parsed
+without the prototype.
+
+The interesting thing about & is that you can generate new syntax with it:
+
+    sub try (&$) {
+	my($try,$catch) = @_;
+	eval { &$try };
+	if ($@) {
+	    local $_ = $@;
+	    &$catch;
+	}
+    }
+    sub catch (&) { @_ }
+
+    try {
+	die "phooey";
+    } catch {
+	/phooey/ and print "unphooey\n";
+    };
+
+That prints "unphooey".  (Yes, there are still unresolved
+issues having to do with the visibility of @_.  I'm ignoring that
+question for the moment.  (But note that if we make @_ lexically
+scoped, those anonymous subroutines can act like closures... (Gee,
+is this sounding a little Lispish?  (Nevermind.))))
+
+And here's a reimplementation of grep:
+
+    sub mygrep (&@) {
+	my $code = shift;
+	my @result;
+	foreach $_ (@_) {
+	    push(@result, $_) if &$ref;
+	}
+	@result;
+    }
 
-=head2 Overriding builtin functions
+Some folks would prefer full alphanumeric prototypes.  Alphanumerics have
+been intentionally left out of prototypes for the express purpose of
+someday in the future adding named, formal parameters.  The current
+mechanism's main goal is to let module writers provide better diagnostics
+for module users.  Larry feels the notation quite understandable to Perl
+programmers, and that it will not intrude greatly upon the meat of the
+module, nor make it harder to read.  The line noise is visually
+encapsulated into a small pill that's easy to swallow.
+
+It's probably best to prototype new functions, not retrofit prototyping
+into older ones.  That's because you must be especially careful about
+silent impositions of differing list versus scalar contexts.  For example,
+if you decide that a function should take just one parameter, like this:
+
+    sub func ($) {
+	my $n = shift;
+	print "you gave me $n\n";
+    } 
+
+and someone has been calling it with an array or expression
+returning a list:
+
+    func(@foo);
+    func( split /:/ );
+
+Then you've just supplied an automatic scalar() in front of their
+argument, which can be more than a bit surprising.  The old @foo
+which used to hold one thing doesn't get passed in.  Instead,
+the func() now gets passed in 1, that is, the number of elments
+in @foo.  And the split() gets called in a scalar context and
+starts scribbling on your @_ parameter list.
+
+This is all very powerful, of course, and should only be used in moderation
+to make the world a better place.  
+
+=head2 Overriding Builtin Functions
 
 Many builtin functions may be overridden, though this should only be
 tried occasionally and for good reason.  Typically this might be
@@ -201,10 +728,37 @@ question using eval, and then execute that subroutine using a special
 form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
 without a trace.  (See the standard C<AutoLoader> module, for example.)
 But an C<AUTOLOAD> routine can also just emulate the routine and never
-define it.  A good example of this is the standard Shell module, which
+define it.   For example, let's pretend that a function that wasn't defined
+should just call system() with those arguments.  All you'd do is this:
+
+    sub AUTOLOAD {
+	my $program = $AUTOLOAD;
+	$program =~ s/.*:://;
+	system($program, @_);
+    } 
+    date();
+    who('am', i');
+    ls('-l');
+
+In fact, if you preclare the functions you want to call that way, you don't
+even need the parentheses:
+
+    use subs qw(date who ls);
+    date;
+    who "am", "i";
+    ls -l;
+
+A more complete example of this is the standard Shell module, which
 can treat undefined subroutine calls as calls to Unix programs.
 
-There are mechanisms available for modules to help them split themselves
-up into autoloadable files to be used with the standard AutoLoader module.
-See the document on extensions.
+Mechanisms are available for modules writers to help split the modules
+up into autoloadable files.  See the standard AutoLoader module described
+in L<Autoloader>, the standard SelfLoader modules in L<SelfLoader>, and
+the document on adding C functions to perl code in L<perlxs>.
+
+=head1 SEE ALSO
 
+See L<perlref> for more on references.  See L<perlxs> if you'd
+like to learn about calling C subroutines from perl.  See 
+L<perlmod> to learn about bundling up your functions in 
+separate files.