podcheck: Improve heuristics for L<>

podcheck.t uses heuristics to decide if something like a C<> should
instead be a L<>.  As noted in the comments, this adds some more checks
to eliminate some false positives

diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index c8d3c15da0e193395d10d07ff0d436c2499ffb84..fc99ca96dbab9ad15f16f438b2c638bdf6f13247 100644 (file)
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -167,7 +167,6 @@ dist/safe/safe.pm   empty section in previous paragraph     1
 dist/selfloader/lib/selfloader.pm      Verbatim line length including indents exceeds 80 by    14
 dist/storable/storable.pm      Verbatim line length including indents exceeds 80 by    4
 dist/thread-queue/lib/thread/queue.pm  Verbatim line length including indents exceeds 80 by    4
-dist/threads-shared/lib/threads/shared.pm      ? Should you be using L<...> instead of 1
 dist/threads/lib/threads.pm    Verbatim line length including indents exceeds 80 by    3
 ext/b/b.pm     Verbatim line length including indents exceeds 80 by    1
 ext/b/b/concise.pm     Verbatim line length including indents exceeds 80 by    1
@@ -175,7 +174,6 @@ ext/devel-peek/peek.pm      ? Should you be using L<...> instead of 2
 ext/devel-peek/peek.pm Verbatim line length including indents exceeds 80 by    2
 ext/dynaloader/dynaloader.pm   Verbatim line length including indents exceeds 80 by    1
 ext/file-glob/glob.pm  Verbatim line length including indents exceeds 80 by    15
-ext/hash-util-fieldhash/lib/hash/util/fieldhash.pm     ? Should you be using L<...> instead of 1
 ext/hash-util-fieldhash/lib/hash/util/fieldhash.pm     Verbatim line length including indents exceeds 80 by    2
 ext/i18n-langinfo/langinfo.pm  Verbatim line length including indents exceeds 80 by    1
 ext/opcode/opcode.pm   Verbatim line length including indents exceeds 80 by    10
@@ -195,14 +193,13 @@ os2/os2/os2-rexx/dll/dll.pm       Verbatim line length including indents exceeds 80 by
 os2/os2/os2-rexx/rexx.pm       Verbatim line length including indents exceeds 80 by    1
 pod/perl.pod   Verbatim line length including indents exceeds 80 by    9
 pod/perlaix.pod        Verbatim line length including indents exceeds 80 by    11
-pod/perlapi.pod        ? Should you be using L<...> instead of 87
+pod/perlapi.pod        ? Should you be using L<...> instead of 86
 pod/perlapi.pod        Apparent broken link    1
 pod/perlapi.pod        Verbatim line length including indents exceeds 80 by    144
 pod/perlapi.pod        unresolved internal link        3
 pod/perlapio.pod       Verbatim line length including indents exceeds 80 by    5
 pod/perlbeos.pod       ? Should you be using F<...> or maybe L<...> instead of 4
 pod/perlbook.pod       Verbatim line length including indents exceeds 80 by    1
-pod/perlcall.pod       ? Should you be using L<...> instead of 4
 pod/perlcall.pod       Verbatim line length including indents exceeds 80 by    2
 pod/perlce.pod ? Should you be using L<...> instead of 1
 pod/perlce.pod Verbatim line length including indents exceeds 80 by    2
@@ -212,7 +209,6 @@ pod/perlcygwin.pod  Verbatim line length including indents exceeds 80 by    27
 pod/perldbmfilter.pod  Verbatim line length including indents exceeds 80 by    1
 pod/perldebguts.pod    Verbatim line length including indents exceeds 80 by    68
 pod/perldebtut.pod     Verbatim line length including indents exceeds 80 by    22
-pod/perldebug.pod      ? Should you be using L<...> instead of 2
 pod/perldebug.pod      Verbatim line length including indents exceeds 80 by    3
 pod/perldelta.pod      Pod NAME already used   -1
 pod/perldiag.pod       =item type mismatch     1
@@ -225,7 +221,7 @@ pod/perlembed.pod   Verbatim line length including indents exceeds 80 by    27
 pod/perlfaq2.pod       Verbatim line length including indents exceeds 80 by    1
 pod/perlfaq4.pod       Verbatim line length including indents exceeds 80 by    16
 pod/perlfaq5.pod       Verbatim line length including indents exceeds 80 by    40
-pod/perlfaq6.pod       ? Should you be using L<...> instead of 3
+pod/perlfaq6.pod       ? Should you be using L<...> instead of 2
 pod/perlfaq6.pod       Verbatim line length including indents exceeds 80 by    36
 pod/perlfaq7.pod       Verbatim line length including indents exceeds 80 by    7
 pod/perlfaq8.pod       Verbatim line length including indents exceeds 80 by    20
@@ -235,7 +231,6 @@ pod/perlfunc.pod    There is more than one target   1
 pod/perlfunc.pod       Verbatim line length including indents exceeds 80 by    183
 pod/perlgit.pod        ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perlgit.pod        Verbatim line length including indents exceeds 80 by    14
-pod/perlglossary.pod   ? Should you be using L<...> instead of 1
 pod/perlgpl.pod        Verbatim line length including indents exceeds 80 by    50
 pod/perlguts.pod       ? Should you be using F<...> or maybe L<...> instead of 2
 pod/perlguts.pod       ? Should you be using L<...> instead of 1
@@ -267,7 +262,7 @@ pod/perlnetware.pod Verbatim line length including indents exceeds 80 by    4
 pod/perlnewmod.pod     Verbatim line length including indents exceeds 80 by    1
 pod/perlop.pod Verbatim line length including indents exceeds 80 by    30
 pod/perlos2.pod        ? Should you be using F<...> or maybe L<...> instead of 2
-pod/perlos2.pod        ? Should you be using L<...> instead of 3
+pod/perlos2.pod        ? Should you be using L<...> instead of 1
 pod/perlos2.pod        Apparent broken link    7
 pod/perlos2.pod        Apparent internal link is missing its forward slash     3
 pod/perlos2.pod        Verbatim line length including indents exceeds 80 by    22
@@ -278,7 +273,6 @@ pod/perlperf.pod    Verbatim line length including indents exceeds 80 by    154
 pod/perlpodspec.pod    Verbatim line length including indents exceeds 80 by    9
 pod/perlpodstyle.pod   Verbatim line length including indents exceeds 80 by    1
 pod/perlport.pod       Apparent broken link    27
-pod/perlre.pod ? Should you be using L<...> instead of 1
 pod/perlreapi.pod      Verbatim line length including indents exceeds 80 by    17
 pod/perlrebackslash.pod        Verbatim line length including indents exceeds 80 by    1
 pod/perlref.pod        Verbatim line length including indents exceeds 80 by    1
@@ -286,7 +280,7 @@ pod/perlreguts.pod  Verbatim line length including indents exceeds 80 by    17
 pod/perlrequick.pod    Verbatim line length including indents exceeds 80 by    3
 pod/perlretut.pod      ? Should you be using L<...> instead of 1
 pod/perlretut.pod      Verbatim line length including indents exceeds 80 by    13
-pod/perlrun.pod        ? Should you be using L<...> instead of 3
+pod/perlrun.pod        ? Should you be using L<...> instead of 2
 pod/perlrun.pod        Apparent broken link    3
 pod/perlrun.pod        Verbatim line length including indents exceeds 80 by    17
 pod/perlsec.pod        Verbatim line length including indents exceeds 80 by    1
@@ -295,14 +289,12 @@ pod/perlsolaris.pod       Verbatim line length including indents exceeds 80 by    14
 pod/perlsource.pod     ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perlsource.pod     ? Should you be using L<...> instead of 1
 pod/perlsub.pod        ? Should you be using F<...> or maybe L<...> instead of 3
-pod/perlsub.pod        ? Should you be using L<...> instead of 1
 pod/perlsub.pod        Verbatim line length including indents exceeds 80 by    4
 pod/perlsymbian.pod    ? Should you be using L<...> instead of 2
 pod/perlsymbian.pod    Verbatim line length including indents exceeds 80 by    20
 pod/perlsyn.pod        Verbatim line length including indents exceeds 80 by    7
 pod/perlthrtut.pod     Verbatim line length including indents exceeds 80 by    5
 pod/perltie.pod        Verbatim line length including indents exceeds 80 by    13
-pod/perltodo.pod       ? Should you be using L<...> instead of 1
 pod/perltodo.pod       Verbatim line length including indents exceeds 80 by    7
 pod/perltodo.pod       empty section in previous paragraph     2
 pod/perltoot.pod       Verbatim line length including indents exceeds 80 by    1
@@ -311,14 +303,11 @@ pod/perltrap.pod  Verbatim line length including indents exceeds 80 by    15
 pod/perltru64.pod      ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perltru64.pod      Verbatim line length including indents exceeds 80 by    4
 pod/perlunicode.pod    Verbatim line length including indents exceeds 80 by    16
-pod/perlunifaq.pod     ? Should you be using L<...> instead of 1
 pod/perlunifaq.pod     empty section in previous paragraph     1
 pod/perluniintro.pod   Verbatim line length including indents exceeds 80 by    3
 pod/perluniprops.pod   =item type mismatch     6
-pod/perlutil.pod       ? Should you be using L<...> instead of 1
 pod/perlvar.pod        Verbatim line length including indents exceeds 80 by    9
 pod/perlvms.pod        ? Should you be using F<...> or maybe L<...> instead of 1
-pod/perlvms.pod        ? Should you be using L<...> instead of 1
 pod/perlvms.pod        Verbatim line length including indents exceeds 80 by    2
 pod/perlwin32.pod      Verbatim line length including indents exceeds 80 by    12
 pod/perlxs.pod Apparent internal link is missing its forward slash     1
@@ -329,7 +318,6 @@ porting/expand-macro.pl     Verbatim line length including indents exceeds 80 by    2
 porting/how_to_write_a_perldelta.pod   There is no NAME        1
 porting/how_to_write_a_perldelta.pod   Verbatim line length including indents exceeds 80 by    3
 porting/pumpkin.pod    Verbatim line length including indents exceeds 80 by    9
-porting/release_managers_guide.pod     ? Should you be using L<...> instead of 2
 porting/release_managers_guide.pod     Verbatim line length including indents exceeds 80 by    11
 porting/release_managers_guide.pod     Verbatim paragraph in NAME section      1
 porting/release_schedule.pod   There is no NAME        1
@@ -345,9 +333,8 @@ lib/benchmark.pm    Verbatim line length including indents exceeds 80 by    4
 lib/cpan/debug.pm      There is no NAME        1
 lib/cpan/handleconfig.pm       =head2 without preceding higher level   1
 lib/cpan/handleconfig.pm       There is no NAME        1
-lib/class/struct.pm    ? Should you be using L<...> instead of 1
 lib/class/struct.pm    Verbatim line length including indents exceeds 80 by    7
-lib/config.pod ? Should you be using L<...> instead of 24
+lib/config.pod ? Should you be using L<...> instead of 22
 lib/config.pod nested commands F<...F<...>...> 3
 lib/db.pm      Verbatim line length including indents exceeds 80 by    2
 lib/dbm_filter.pm      Verbatim line length including indents exceeds 80 by    1
@@ -377,12 +364,11 @@ lib/deprecate.pm  Verbatim line length including indents exceeds 80 by    2
 lib/integer.pm Verbatim line length including indents exceeds 80 by    1
 lib/overload.pm        Apparent broken link    1
 lib/overload.pm        Verbatim line length including indents exceeds 80 by    1
-lib/perl5db.pl ? Should you be using L<...> instead of 2
+lib/perl5db.pl ? Should you be using L<...> instead of 1
 lib/perl5db.pl Verbatim line length including indents exceeds 80 by    1
 lib/strict.pm  Verbatim line length including indents exceeds 80 by    1
 lib/utf8.pm    Verbatim line length including indents exceeds 80 by    4
 lib/version.pod        Verbatim line length including indents exceeds 80 by    2
-lib/version/internals.pod      ? Should you be using L<...> instead of 1
 lib/version/internals.pod      Apparent broken link    1
 lib/version/internals.pod      Verbatim line length including indents exceeds 80 by    2
 lib/vmsish.pm  Verbatim line length including indents exceeds 80 by    1

diff --git a/t/porting/podcheck.t b/t/porting/podcheck.t
index fb539115a979447af3422ddf86301a05adc911fd..7e4320c455f1bb34a2a44fc0a58906000b4a6237 100644 (file)
--- a/t/porting/podcheck.t
+++ b/t/porting/podcheck.t
@@ -656,14 +656,46 @@ package My::Pod::Checker {      # Extend Pod::Checker
         # If looks like a reference to other documentation by containing the
         # word 'See' and then a likely pod directive, warn.
 
-        while ($paragraph =~ m{ \b See \s+ ( ( [^L] ) <
+        while ($paragraph =~ m{ \b See \s+
+                                ( ( [^L] ) <
                                 ( [^<]*? )  # The not-< excludes nested C<L<...
-                                > ) }ixg) {
-            my $construct = $1;
+                                > )
+                                ( \s+ (?: under | in ) \s+ L< )?
+                            }ixg) {
+            my $construct = $1;     # The whole thing
             my $type = $2;
             my $interior = $3;
-            if ($interior !~ /$non_pods/
-                && $construct !~ /$C_path_re/g) {
+            my $trailing = $4;      # After the whole thing ending in "L<"
+
+            # Now, find what the module or man page name within the construct
+            # would be if it actually has L<> syntax.  If it doesn't have that
+            # syntax, will set the module to the entire interior.
+            $interior =~ m/ ^
+                            (?: [^|]+ \| )? # Optional arbitrary text ending in
+                                            # "|"
+                            ( .+? )         # module, etc. name
+                            (?: \/ .+ )?    # target within module
+                            $
+                         /xs;
+            my $module = $1;
+            if (! defined $trailing # not referring to something in another
+                                    # section
+                && $interior !~ /$non_pods/
+
+                # C<> that look like files have their own message below, so
+                # exclude them
+                && $construct !~ /$C_path_re/g
+
+                # There can't be spaces (I think) in module names or man
+                # pages
+                && $module !~ / \s /x
+
+                # F<> that end in eg \.pl are almost certainly ok, as are
+                # those that look like a path with multiple "/" chars
+                && ($type ne "F"
+                    || ($interior !~ /\.\w+$/ && $interior !~ /\/.+\//)
+                   )
+            ) {
                 $self->poderror({ -line => $line, -file => $file,
                     -msg => $see_not_linked,
                     parameter => $construct