Deprecate (or at least discourage) :raw.

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d6dcf49..f2ca525 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2628,16 +2628,16 @@ and C<IPC::SysV::Msg> documentation.
 
 =item my TYPE EXPR
 
-=item my EXPR : ATTRIBUTES
+=item my EXPR : ATTRS
 
-=item my TYPE EXPR : ATTRIBUTES
+=item my TYPE EXPR : ATTRS
 
 A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>.  If
-more than one value is listed, the list must be placed in parentheses.
+enclosing block, file, or C<eval>.  If more than one value is listed,
+the list must be placed in parentheses.
 
-The use of TYPE and ATTRIBUTES is considered experimental and subject
-to change.  TYPE is currently bound to the use of C<fields> pragma,
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
 and attributes are handled using the C<attributes> pragma, or starting
 from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
@@ -3070,9 +3070,9 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR TYPE
 
-=item our EXPR : ATTRIBUTES
+=item our EXPR : ATTRS
 
-=item our TYPE EXPR : ATTRIBUTES
+=item our TYPE EXPR : ATTRS
 
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
@@ -3115,8 +3115,8 @@ package, Perl will emit warnings if you have asked for them.
 An C<our> declaration may also have a list of attributes associated
 with it.
 
-The use of TYPE and ATTRIBUTES is considered experimental and subject
-to change.  TYPE is currently bound to the use of C<fields> pragma,
+The exact semantics and interface of TYPE and ATTRS are still
+evolving.  TYPE is currently bound to the use of C<fields> pragma,
 and attributes are handled using the C<attributes> pragma, or starting
 from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
@@ -4503,8 +4503,7 @@ sockets but not socketpair.
 =item sort LIST
 
 In list context, this sorts the LIST and returns the sorted list value.
-In scalar context, sort doesn't do anything and an undefined value is
-returned.
+In scalar context, the behaviour of C<sort()> is undefined.
 
 If SUBNAME or BLOCK is omitted, C<sort>s in standard string comparison
 order.  If SUBNAME is specified, it gives the name of a subroutine
@@ -5219,17 +5218,22 @@ out the names of those files that contain a match:
        print $file, "\n";
     }
 
-=item sub BLOCK
+=item sub NAME BLOCK
 
-=item sub NAME
+=item sub NAME (PROTO) BLOCK
 
-=item sub NAME BLOCK
+=item sub NAME : ATTRS BLOCK
+
+=item sub NAME (PROTO) : ATTRS BLOCK
+
+This is subroutine definition, not a real function I<per se>.
+Without a BLOCK it's just a forward declaration.  Without a NAME,
+it's an anonymous function declaration, and does actually return
+a value: the CODE ref of the closure you just created.
 
-This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes or attributes), it's just a forward declaration.
-Without a NAME, it's an anonymous function declaration, and does actually
-return a value: the CODE ref of the closure you just created.  See L<perlsub>
-and L<perlref> for details.
+See L<perlsub> and L<perlref> for details about subroutines and
+references, and L<attributes> and L<Attribute::Handlers> for more
+information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT