Remove duplicate paragraph from perlref.pod

[perl5.git] / pod / perllexwarn.pod

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index 45a7f5f..3b6b827 100644 (file)
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -91,7 +91,7 @@ a block of code. You might expect this to be enough to do the trick:
      }
 
 When this code is run with the B<-w> flag, a warning will be produced
-for the C<$a> line -- C<"Reversed += operator">.
+for the C<$a> line:  C<"Reversed += operator">.
 
 The problem is that Perl has both compile-time and run-time warnings. To
 disable compile-time warnings you need to rewrite the code like this:
@@ -158,7 +158,7 @@ Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
 
 =head2 Backward Compatibility
 
-If you are used with working with a version of Perl prior to the
+If you are used to working with a version of Perl prior to the
 introduction of lexically scoped warnings, or have code that uses both
 lexical warnings and C<$^W>, this section will describe how they interact.
 
@@ -169,7 +169,7 @@ How Lexical Warnings interact with B<-w>/C<$^W>:
 =item 1.
 
 If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
-control warnings is used and neither C<$^W> or the C<warnings> pragma
+control warnings is used and neither C<$^W> nor the C<warnings> pragma
 are used, then default warnings will be enabled and optional warnings
 disabled.
 This means that legacy code that doesn't attempt to control the warnings
@@ -177,7 +177,7 @@ will work unchanged.
 
 =item 2.
 
-The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this
+The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
 means that any legacy code that currently relies on manipulating C<$^W>
 to control warning behavior will still work as is. 
 
@@ -212,101 +212,109 @@ to be enabled/disabled in isolation.
 
 The current hierarchy is:
 
-  all -+
-       |
-       +- closure
-       |
-       +- deprecated
-       |
-       +- exiting
-       |
-       +- glob
-       |
-       +- io -----------+
-       |                |
-       |                +- closed
-       |                |
-       |                +- exec
-       |                |
-       |                +- layer
-       |                |
-       |                +- newline
-       |                |
-       |                +- pipe
-       |                |
-       |                +- unopened
-       |
-       +- imprecision
-       |
-       +- misc
-       |
-       +- numeric
-       |
-       +- once
-       |
-       +- overflow
-       |
-       +- pack
-       |
-       +- portable
-       |
-       +- recursion
-       |
-       +- redefine
-       |
-       +- regexp
-       |
-       +- severe -------+
-       |                |
-       |                +- debugging
-       |                |
-       |                +- inplace
-       |                |
-       |                +- internal
-       |                |
-       |                +- malloc
-       |
-       +- signal
-       |
-       +- substr
-       |
-       +- syntax -------+
-       |                |
-       |                +- ambiguous
-       |                |
-       |                +- bareword
-       |                |
-       |                +- digit
-       |                |
-       |                +- illegalproto
-       |                |
-       |                +- parenthesis
-       |                |
-       |                +- precedence
-       |                |
-       |                +- printf
-       |                |
-       |                +- prototype
-       |                |
-       |                +- qw
-       |                |
-       |                +- reserved
-       |                |
-       |                +- semicolon
-       |
-       +- taint
-       |
-       +- threads
-       |
-       +- uninitialized
-       |
-       +- unpack
-       |
-       +- untie
-       |
-       +- utf8
-       |
-       +- void
+    all -+
+         |
+         +- closure
+         |
+         +- deprecated
+         |
+         +- exiting
+         |
+         +- experimental
+         |
+         +- glob
+         |
+         +- imprecision
+         |
+         +- io ------------+
+         |                 |
+         |                 +- closed
+         |                 |
+         |                 +- exec
+         |                 |
+         |                 +- layer
+         |                 |
+         |                 +- newline
+         |                 |
+         |                 +- pipe
+         |                 |
+         |                 +- unopened
+         |
+         +- misc
+         |
+         +- numeric
+         |
+         +- once
+         |
+         +- overflow
+         |
+         +- pack
+         |
+         +- portable
+         |
+         +- recursion
+         |
+         +- redefine
+         |
+         +- regexp
+         |
+         +- severe --------+
+         |                 |
+         |                 +- debugging
+         |                 |
+         |                 +- inplace
+         |                 |
+         |                 +- internal
+         |                 |
+         |                 +- malloc
+         |
+         +- signal
+         |
+         +- substr
+         |
+         +- syntax --------+
+         |                 |
+         |                 +- ambiguous
+         |                 |
+         |                 +- bareword
+         |                 |
+         |                 +- digit
+         |                 |
+         |                 +- illegalproto
+         |                 |
+         |                 +- parenthesis
+         |                 |
+         |                 +- precedence
+         |                 |
+         |                 +- printf
+         |                 |
+         |                 +- prototype
+         |                 |
+         |                 +- qw
+         |                 |
+         |                 +- reserved
+         |                 |
+         |                 +- semicolon
+         |
+         +- taint
+         |
+         +- threads
+         |
+         +- uninitialized
+         |
+         +- unpack
+         |
+         +- untie
+         |
+         +- utf8 ----------+
+         |                 |
+         |                 +- non_unicode
+         |                 |
+         |                 +- nonchar
+         |                 |
+         |                 +- surrogate
+         |
+         +- void
 
 Just like the "strict" pragma any of these categories can be combined
 
@@ -329,6 +337,18 @@ Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a
 sub-category of the "syntax" category. It is now a top-level category
 in its own right.
 
+=head2 Individual Warning IDs
+
+The "experimental" warnings category, added in Perl 5.18,
+contains IDs for individual warnings, so that each warning can
+be turned on or off.  Currently there is only one such warning,
+labelled "experimental:lexical_subs".  You enable and disable
+it like this:
+
+    use warnings "experimental:lexical_subs";
+    no  warnings "experimental:lexical_subs";
+
+The plan is to extend this convention to all warnings in a future release.
 
 =head2 Fatal Warnings
 X<warning, fatal>
@@ -520,6 +540,16 @@ a warning.
 Notice also that the warning is reported at the line where the object is first
 used.
 
+When registering new categories of warning, you can supply more names to
+warnings::register like this:
+
+    package MyModule;
+    use warnings::register qw(format precision);
+
+    ...
+
+    warnings::warnif('MyModule::format', '...');
+
 =head1 SEE ALSO
 
 L<warnings>, L<perldiag>.