re.pm: Nits in pod

This has clarifications, grammar changes, and reflowing to fit into 79
columns

diff --git a/ext/re/re.pm b/ext/re/re.pm
index 1242595..f770839 100644 (file)
--- a/ext/re/re.pm
+++ b/ext/re/re.pm
@@ -4,7 +4,7 @@ package re;
 use strict;
 use warnings;
 
-our $VERSION     = "0.21";
+our $VERSION     = "0.22";
 our @ISA         = qw(Exporter);
 our @EXPORT_OK   = ('regmust',
                     qw(is_regexp regexp_pattern
@@ -235,14 +235,16 @@ re - Perl pragma to alter regular expression behaviour
 
     $pat = '(?{ $foo = 1 })';
     use re 'eval';
-    /foo${pat}bar/;               # won't fail (when not under -T switch)
+    /foo${pat}bar/;               # won't fail (when not under -T
+                                   # switch)
 
     {
        no re 'taint';             # the default
        ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
 
        no re 'eval';              # the default
-       /foo${pat}bar/;            # disallowed (with or without -T switch)
+       /foo${pat}bar/;            # disallowed (with or without -T
+                                   # switch)
     }
 
     use re '/ix';
@@ -251,22 +253,27 @@ re - Perl pragma to alter regular expression behaviour
     "FOO" =~ /foo/; # just /i implied
 
     use re 'debug';               # output debugging info during
-    /^(.*)$/s;                    #     compile and run time
+    /^(.*)$/s;                    # compile and run time
 
 
-    use re 'debugcolor';          # same as 'debug', but with colored output
+    use re 'debugcolor';          # same as 'debug', but with colored
+                                   # output
     ...
 
-    use re qw(Debug All);          # Finer tuned debugging options.
-    use re qw(Debug More);
-    no re qw(Debug ALL);           # Turn of all re debugging in this scope
+    use re qw(Debug All);          # Same as "use re 'debug'", but you
+                                   # can use "Debug" with things other
+                                   # than 'All'
+    use re qw(Debug More);         # 'All' plus output more details
+    no re qw(Debug ALL);           # Turn on (almost) all re debugging
+                                   # in this scope
 
     use re qw(is_regexp regexp_pattern); # import utility functions
     my ($pat,$mods)=regexp_pattern(qr/foo/i);
     if (is_regexp($obj)) { 
         print "Got regexp: ",
-            scalar regexp_pattern($obj); # just as perl would stringify it
-    }                                    # but no hassle with blessed re's.
+            scalar regexp_pattern($obj); # just as perl would stringify
+    }                                    # it but no hassle with blessed
+                                         # re's.
 
 (We use $^X in these examples because it's tainted by default.)
 
@@ -409,7 +416,7 @@ Extra debugging of how tries execute.
 
 =item INTUIT
 
-Enable debugging of start point optimisations.
+Enable debugging of start-point optimisations.
 
 =back
 
@@ -443,7 +450,7 @@ states as well. This output from this can be quite large.
 
 =item OPTIMISEM
 
-Enable enhanced optimisation debugging and start point optimisations.
+Enable enhanced optimisation debugging and start-point optimisations.
 Probably not useful except when debugging the regexp engine itself.
 
 =item OFFSETS
@@ -476,7 +483,8 @@ These are useful shortcuts to save on the typing.
 
 =item ALL
 
-Enable all options at once except OFFSETS, OFFSETSDBG and BUFFERS
+Enable all options at once except OFFSETS, OFFSETSDBG and BUFFERS.
+(To get every single option without exception, use both ALL and EXTRA.)
 
 =item All
 
@@ -488,14 +496,14 @@ Enable DUMP and all execute options. Equivalent to:
 
 =item More
 
-Enable TRIEM and all execute compile and execute options.
+Enable the options enabled by "All", plus STATE, TRIEC, and TRIEM.
 
 =back
 
 =back
 
 As of 5.9.5 the directive C<use re 'debug'> and its equivalents are
-lexically scoped, as the other directives are.  However they have both
+lexically scoped, as are the other directives.  However they have both
 compile-time and run-time effects.
 
 =head2 Exportable Functions

diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 42a1bca..b1882bd 100644 (file)
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -1,4 +1,4 @@
-# This file is the data file for t/porting/podcheck.t.
+# This file is the data file for porting/podcheck.t.
 # There are three types of lines.
 # Comment lines are white-space only or begin with a '#', like this one.  Any
 #   changes you make to the comment lines will be lost when the file is
@@ -197,7 +197,6 @@ ext/pod-html/testdir/perlvar-copy.pod       ? Should you be using L<...> instead of 3
 ext/pod-html/testdir/perlvar-copy.pod  Apparent broken link    2
 ext/pod-html/testdir/perlvar-copy.pod  Verbatim line length including indents exceeds 79 by    6
 ext/posix/lib/posix.pod        Verbatim line length including indents exceeds 79 by    13
-ext/re/re.pm   Verbatim line length including indents exceeds 79 by    6
 ext/vms-dclsym/dclsym.pm       ? Should you be using L<...> instead of 1
 ext/vms-dclsym/dclsym.pm       Verbatim line length including indents exceeds 79 by    1
 ext/vms-stdio/stdio.pm Verbatim line length including indents exceeds 79 by    1