This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch to update Pod::Checker into blead
authorKarl Williamson <khw@cpan.org>
Fri, 27 May 2016 17:24:57 +0000 (11:24 -0600)
committerKarl Williamson <khw@cpan.org>
Fri, 27 May 2016 17:24:57 +0000 (11:24 -0600)
This merge branch contains two commits, which should be considered
inseperable.  The first updates Pod::Checker, and the second changes
podcheck.t to use the new Pod::Checker.

This is the biggest remaining step in allowing Pod::Parser to be
removed from core.  podcheck.t still uses Pod::Parser to extract just
the pod from files.  That dependency can be removed when Pod::Simple
changes to allow equivalent functionality, something I myself am working
on.

There are two cpan .t files (both in pod2usage) that use subcomponents
of Pod::Parser (Pod::Find and Pod::PlainText).  There appears to be
similar functionality in Pod::Simple, so that shouldn't be too hard to
fix, but I haven't looked further than finding that these aren't drop-in
replacements.  The pod2usage maintainer has been notified.

MANIFEST
cpan/Pod-Checker/lib/Pod/Checker.pm
cpan/Pod-Checker/scripts/podchecker.PL
cpan/Pod-Checker/t/pod/podchkenc.xr
cpan/Pod-Checker/t/pod/podchklink.t [new file with mode: 0644]
cpan/Pod-Checker/t/pod/poderrs.t
cpan/Pod-Checker/t/pod/poderrs.xr
cpan/Pod-Checker/t/pod/testpchk.pl
t/porting/known_pod_issues.dat
t/porting/podcheck.t

index 5e9eb7b..aa157f8 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1845,6 +1845,7 @@ cpan/Pod-Checker/t/pod/contains_bad_pod.xr
 cpan/Pod-Checker/t/pod/empty.xr
 cpan/Pod-Checker/t/pod/podchkenc.t
 cpan/Pod-Checker/t/pod/podchkenc.xr
+cpan/Pod-Checker/t/pod/podchklink.t
 cpan/Pod-Checker/t/pod/poderrs.t
 cpan/Pod-Checker/t/pod/poderrs.xr
 cpan/Pod-Checker/t/pod/selfcheck.t
index b69f338..5188f96 100644 (file)
@@ -2,31 +2,28 @@
 # Pod/Checker.pm -- check pod documents for syntax errors
 #
 # Copyright (C) 1994-2000 by Bradford Appleton. All rights reserved.
-# This file is part of "PodParser". PodParser is free software;
-# you can redistribute it and/or modify it under the same terms
-# as Perl itself.
+# This is free software; you can redistribute it and/or modify it under the
+# same terms as Perl itself.
 #############################################################################
 
 package Pod::Checker;
 use strict;
+use warnings;
+use Data::Dumper
 
-use vars qw($VERSION @ISA @EXPORT %VALID_COMMANDS %VALID_SEQUENCES);
-$VERSION = '1.72';  ## Current version of this package
-require  5.005;    ## requires this Perl version or later
-
-use Pod::ParseUtils; ## for hyperlinks and lists
+our $VERSION = '1.72';  ## Current version of this package
 
 =head1 NAME
 
-Pod::Checker, podchecker() - check pod documents for syntax errors
+Pod::Checker - check pod documents for syntax errors
 
 =head1 SYNOPSIS
 
   use Pod::Checker;
 
-  $num_errors = podchecker($filepath, $outputpath, %options);
+  $syntax_okay = podchecker($filepath, $outputpath, %options);
 
-  my $checker = new Pod::Checker %options;
+  my $checker = Pod::Checker->new(%options);
   $checker->parse_from_file($filepath, \*STDERR);
 
 =head1 OPTIONS/ARGUMENTS
@@ -48,6 +45,10 @@ This function can take a hash of options:
 Turn warnings on/off. I<val> is usually 1 for on, but higher values
 trigger additional warnings. See L<"Warnings">.
 
+=item B<-quiet> =E<gt> I<val>
+
+If C<val> is true, do not print any errors/warnings.
+
 =back
 
 =head1 DESCRIPTION
@@ -111,42 +112,56 @@ heading!
 
 =item * =over on line I<N> without closing =back
 
+=item * You forgot a '=back' before '=headI<N>'
+
+=item * =over is the last thing in the document?!
+
 The C<=over> command does not have a corresponding C<=back> before the
 next heading (C<=head1> or C<=head2>) or the end of the file.
 
-=item * =item without previous =over
+=item * '=item' outside of any '=over'
 
-=item * =back without previous =over
+=item * =back without =over
 
 An C<=item> or C<=back> command has been found outside a
 C<=over>/C<=back> block.
 
-=item * No argument for =begin
+=item * Can't have a 0 in =over I<N>
+
+You need to indent a strictly positive number of spaces, not 0.
+
+=item * =over should be: '=over' or '=over positive_number'
+
+Either have an argumentless =over, or have its argument a strictly positive number.
+
+=item * =begin I<TARGET> without matching =end I<TARGET>
+
+A C<=begin> command was found that has no matching =end command.
+
+=item * =begin without a target?
 
 A C<=begin> command was found that is not followed by the formatter
 specification.
 
-=item * =end without =begin
+=item * =end I<TARGET> without matching =begin.
 
 A standalone C<=end> command was found.
 
-=item * Nested =begin's
+=item * '=end' without a target?
 
-There were at least two consecutive C<=begin> commands without
-the corresponding C<=end>. Only one C<=begin> may be active at
-a time.
+'=end' directives need to have a target, just like =begin directives.
 
-=item * =for without formatter specification
+=item * '=end I<TARGET>' is invalid.
 
-There is no specification of the formatter after the C<=for> command.
+I<TARGET> needs to be one word
 
-=item * Apparent command =foo not preceded by blank line
+=item * =end I<CONTENT> doesn't match =begin I<TARGET>
 
-A command which has ended up in the middle of a paragraph or other command,
-such as
+I<CONTENT> needs to match =begin's I<TARGET>.
 
-  =item one
-  =item two <-- bad
+=item * =for without a target?
+
+There is no specification of the formatter after the C<=for> command.
 
 =item * unresolved internal link I<NAME>
 
@@ -154,60 +169,58 @@ The given link to I<NAME> does not have a matching node in the current
 POD. This also happened when a single word node name is not enclosed in
 C<"">.
 
-=item * Unknown command "I<CMD>"
+=item * Unknown directive: I<CMD>
 
 An invalid POD command has been found. Valid are C<=head1>, C<=head2>,
 C<=head3>, C<=head4>, C<=over>, C<=item>, C<=back>, C<=begin>, C<=end>,
 C<=for>, C<=pod>, C<=cut>
 
-=item * Unknown interior-sequence "I<SEQ>"
+=item * Deleting unknown formatting code I<SEQ>
 
 An invalid markup command has been encountered. Valid are:
 C<BE<lt>E<gt>>, C<CE<lt>E<gt>>, C<EE<lt>E<gt>>, C<FE<lt>E<gt>>,
 C<IE<lt>E<gt>>, C<LE<lt>E<gt>>, C<SE<lt>E<gt>>, C<XE<lt>E<gt>>,
 C<ZE<lt>E<gt>>
 
-=item * nested commands I<CMD>E<lt>...I<CMD>E<lt>...E<gt>...E<gt>
+=item * Unterminated I<SEQ>E<lt>E<gt> sequence
 
-Two nested identical markup commands have been found. Generally this
-does not make sense.
+An unclosed formatting code
 
-=item * garbled entity I<STRING>
+=item * An EE<lt>...E<gt> surrounding strange content
 
 The I<STRING> found cannot be interpreted as a character entity.
 
-=item * Entity number out of range
+=item * An empty EE<lt>E<gt>
 
-An entity specified by number (dec, hex, oct) is out of range (1-255).
+=item * An empty C<< LE<lt>E<gt> >>
 
-=item * malformed link LE<lt>E<gt>
+=item * An empty XE<lt>E<gt>
 
-The link found cannot be parsed because it does not conform to the
-syntax described in L<perlpod>.
+There needs to be content inside E, L, and X formatting codes.
 
-=item * nonempty ZE<lt>E<gt>
+=item * A non-empty ZE<lt>E<gt>
 
 The C<ZE<lt>E<gt>> sequence is supposed to be empty.
 
-=item * empty XE<lt>E<gt>
-
-The index entry specified contains nothing but whitespace.
-
 =item * Spurious text after =pod / =cut
 
 The commands C<=pod> and C<=cut> do not take any arguments.
 
-=item * Spurious =cut command
+=item * =back doesn't take any parameters, but you said =back I<ARGUMENT>
 
-A C<=cut> command was found without a preceding POD paragraph.
+The C<=back> command does not take any arguments.
 
-=item * Spurious =pod command
+=item * =pod directives shouldn't be over one line long!  Ignoring all I<N> lines of content
 
-A C<=pod> command was found after a preceding POD paragraph.
+Self explanatory
 
-=item * Spurious character(s) after =back
+=item * =cut found outside a pod block.
 
-The C<=back> command does not take any arguments.
+A '=cut' directive found in the middle of non-POD
+
+=item * Invalid =encoding syntax: I<CONTENT>
+
+Syntax error in =encoding directive
 
 =back
 
@@ -217,7 +230,12 @@ These may not necessarily cause trouble, but indicate mediocre style.
 
 =over 4
 
-=item * multiple occurrence of link target I<name>
+=item * nested commands I<CMD>E<lt>...I<CMD>E<lt>...E<gt>...E<gt>
+
+Two nested identical markup commands have been found. Generally this
+does not make sense.
+
+=item * multiple occurrences (I<N>) of link target I<name>
 
 The POD file has some C<=item> and/or C<=head> commands that have
 the same text. Potential hyperlinks to such a text cannot be unique then.
@@ -229,59 +247,46 @@ There is some whitespace on a seemingly empty line. POD is very sensitive
 to such things, so this is flagged. B<vi> users switch on the B<list>
 option to avoid this problem.
 
-=begin _disabled_
-
-=item * file does not start with =head
+=item * =item has no contents
 
-The file starts with a different POD directive than head.
-This is most probably something you do not want.
+There is a list C<=item> that has no text contents. You probably want to delete
+empty items.
 
-=end _disabled_
-
-=item * previous =item has no contents
-
-There is a list C<=item> right above the flagged line that has no
-text contents. You probably want to delete empty items.
-
-=item * preceding non-item paragraph(s)
+=item * You can't have =items (as at line I<N>) unless the first thing after the =over is an =item
 
 A list introduced by C<=over> starts with a text or verbatim paragraph,
 but continues with C<=item>s. Move the non-item paragraph out of the
 C<=over>/C<=back> block.
 
-=item * =item type mismatch (I<one> vs. I<two>)
+=item * Expected '=item I<EXPECTED VALUE>'
+
+=item * Expected '=item *'
+
+=item * Possible =item type mismatch: 'I<x>' found leading a supposed definition =item
 
 A list started with e.g. a bullet-like C<=item> and continued with a
 numbered one. This is obviously inconsistent. For most translators the
 type of the I<first> C<=item> determines the type of the list.
 
-=item * I<N> unescaped C<E<lt>E<gt>> in paragraph
+=item * You have '=item x' instead of the expected '=item I<N>'
 
-Angle brackets not written as C<E<lt>ltE<gt>> and C<E<lt>gtE<gt>>
-can potentially cause errors as they could be misinterpreted as
-markup commands. This is only printed when the -warnings level is
-greater than 1.
+Erroneous numbering of =item numbers; they need to ascend consecutively.
 
-=item * Unknown entity
+=item * Unknown E content in EE<lt>I<CONTENT>E<gt>
 
 A character entity was found that does not belong to the standard
-ISO set or the POD specials C<verbar> and C<sol>.
-
-=item * No items in =over
+ISO set or the POD specials C<verbar> and C<sol>. I<Currently, this warning
+only appears if a character entity was found that does not have a Unicode
+character. This should be fixed to adhere to the original warning.>
 
-The list opened with C<=over> does not contain any items.
+=item * empty =over/=back block
 
-=item * No argument for =item
-
-C<=item> without any parameters is deprecated. It should either be followed
-by C<*> to indicate an unordered list, by a number (optionally followed
-by a dot) to indicate an ordered (numbered) list or simple text for a
-definition list.
+The list opened with C<=over> does not contain anything.
 
 =item * empty section in previous paragraph
 
 The previous section (introduced by a C<=head> command) does not contain
-any text. This usually indicates that something is missing. Note: A
+any valid content. This usually indicates that something is missing. Note: A
 C<=head1> followed immediately by C<=head2> does not trigger this warning.
 
 =item * Verbatim paragraph in NAME section
@@ -308,14 +313,6 @@ There are some warnings with respect to malformed hyperlinks:
 There is whitespace at the beginning or the end of the contents of
 LE<lt>...E<gt>.
 
-=item * (section) in '$page' deprecated
-
-There is a section detected in the page name of LE<lt>...E<gt>, e.g.
-C<LE<lt>passwd(2)E<gt>>. POD hyperlinks may point to POD documents only.
-Please write C<CE<lt>passwd(2)E<gt>> instead. Some formatters are able
-to expand this to appropriate code. For links to (builtin) functions,
-please say C<LE<lt>perlfunc/mkdirE<gt>>, without ().
-
 =item * alternative text/node '%s' contains non-escaped | or /
 
 The characters C<|> and C</> are special in the LE<lt>...E<gt> context.
@@ -328,6 +325,11 @@ these literal characters like this:
 
 =back
 
+Note that the line number of the error/warning may refer to the line number of
+the start of the paragraph in which the error/warning exists, not the line 
+number that the error/warning is on. This bug is present in errors/warnings
+related to formatting codes. I<This should be fixed.>
+
 =head1 RETURN VALUE
 
 B<podchecker> returns the number of POD syntax errors found or -1 if
@@ -337,6 +339,14 @@ there were no POD commands at all found in the file.
 
 See L</SYNOPSIS>
 
+=head1 SCRIPTS
+
+The B<podchecker> script that comes with this distribution is a lean wrapper
+around this module. See the online manual with
+
+  podchecker -help
+  podchecker -man
+
 =head1 INTERFACE
 
 While checking, this module collects document properties, e.g. the nodes
@@ -345,169 +355,28 @@ POD translators can use this feature to syntax-check and get the nodes in
 a first pass before actually starting to convert. This is expensive in terms
 of execution time, but allows for very robust conversions.
 
-Since PodParser-1.24 the B<Pod::Checker> module uses only the B<poderror>
+Since v1.24 the B<Pod::Checker> module uses only the B<poderror>
 method to print errors and warnings. The summary output (e.g.
 "Pod syntax OK") has been dropped from the module and has been included in
 B<podchecker> (the script). This allows users of B<Pod::Checker> to
 control completely the output behavior. Users of B<podchecker> (the script)
 get the well-known behavior.
 
+v1.45 inherits from Pod::Simple as opposed to all previous versions
+inheriting from Pod::Parser. Do B<not> use Pod::Simple's interface when
+using Pod::Checker unless it is documented somewhere on this page. I
+repeat, DO B<NOT> USE POD::SIMPLE'S INTERFACE.
+
 =cut
 
 #############################################################################
 
 #use diagnostics;
 use Carp qw(croak);
-use Exporter;
-use Pod::Parser;
-
-@ISA = qw(Pod::Parser);
-@EXPORT = qw(&podchecker);
-
-my %VALID_COMMANDS = (
-    'pod'    =>  1,
-    'cut'    =>  1,
-    'head1'  =>  1,
-    'head2'  =>  1,
-    'head3'  =>  1,
-    'head4'  =>  1,
-    'over'   =>  1,
-    'back'   =>  1,
-    'item'   =>  1,
-    'for'    =>  1,
-    'begin'  =>  1,
-    'end'    =>  1,
-    'encoding' =>  1,
-);
-
-my %VALID_SEQUENCES = (
-    'I'  =>  1,
-    'B'  =>  1,
-    'S'  =>  1,
-    'C'  =>  1,
-    'L'  =>  1,
-    'F'  =>  1,
-    'X'  =>  1,
-    'Z'  =>  1,
-    'E'  =>  1,
-);
-
-# stolen from HTML::Entities
-my %ENTITIES = (
- # Some normal chars that have special meaning in SGML context
- amp    => '&',  # ampersand
-'gt'    => '>',  # greater than
-'lt'    => '<',  # less than
- quot   => '"',  # double quote
-
- # PUBLIC ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML
- AElig  => 'Æ',  # capital AE diphthong (ligature)
- Aacute => 'Á',  # capital A, acute accent
- Acirc  => 'Â',  # capital A, circumflex accent
- Agrave => 'À',  # capital A, grave accent
- Aring  => 'Å',  # capital A, ring
- Atilde => 'Ã',  # capital A, tilde
- Auml   => 'Ä',  # capital A, dieresis or umlaut mark
- Ccedil => 'Ç',  # capital C, cedilla
- ETH    => 'Ð',  # capital Eth, Icelandic
- Eacute => 'É',  # capital E, acute accent
- Ecirc  => 'Ê',  # capital E, circumflex accent
- Egrave => 'È',  # capital E, grave accent
- Euml   => 'Ë',  # capital E, dieresis or umlaut mark
- Iacute => 'Í',  # capital I, acute accent
- Icirc  => 'Î',  # capital I, circumflex accent
- Igrave => 'Ì',  # capital I, grave accent
- Iuml   => 'Ï',  # capital I, dieresis or umlaut mark
- Ntilde => 'Ñ',  # capital N, tilde
- Oacute => 'Ó',  # capital O, acute accent
- Ocirc  => 'Ô',  # capital O, circumflex accent
- Ograve => 'Ò',  # capital O, grave accent
- Oslash => 'Ø',  # capital O, slash
- Otilde => 'Õ',  # capital O, tilde
- Ouml   => 'Ö',  # capital O, dieresis or umlaut mark
- THORN  => 'Þ',  # capital THORN, Icelandic
- Uacute => 'Ú',  # capital U, acute accent
- Ucirc  => 'Û',  # capital U, circumflex accent
- Ugrave => 'Ù',  # capital U, grave accent
- Uuml   => 'Ü',  # capital U, dieresis or umlaut mark
- Yacute => 'Ý',  # capital Y, acute accent
- aacute => 'á',  # small a, acute accent
- acirc  => 'â',  # small a, circumflex accent
- aelig  => 'æ',  # small ae diphthong (ligature)
- agrave => 'à',  # small a, grave accent
- aring  => 'å',  # small a, ring
- atilde => 'ã',  # small a, tilde
- auml   => 'ä',  # small a, dieresis or umlaut mark
- ccedil => 'ç',  # small c, cedilla
- eacute => 'é',  # small e, acute accent
- ecirc  => 'ê',  # small e, circumflex accent
- egrave => 'è',  # small e, grave accent
- eth    => 'ð',  # small eth, Icelandic
- euml   => 'ë',  # small e, dieresis or umlaut mark
- iacute => 'í',  # small i, acute accent
- icirc  => 'î',  # small i, circumflex accent
- igrave => 'ì',  # small i, grave accent
- iuml   => 'ï',  # small i, dieresis or umlaut mark
- ntilde => 'ñ',  # small n, tilde
- oacute => 'ó',  # small o, acute accent
- ocirc  => 'ô',  # small o, circumflex accent
- ograve => 'ò',  # small o, grave accent
- oslash => 'ø',  # small o, slash
- otilde => 'õ',  # small o, tilde
- ouml   => 'ö',  # small o, dieresis or umlaut mark
- szlig  => 'ß',  # small sharp s, German (sz ligature)
- thorn  => 'þ',  # small thorn, Icelandic
- uacute => 'ú',  # small u, acute accent
- ucirc  => 'û',  # small u, circumflex accent
- ugrave => 'ù',  # small u, grave accent
- uuml   => 'ü',  # small u, dieresis or umlaut mark
- yacute => 'ý',  # small y, acute accent
- yuml   => 'ÿ',  # small y, dieresis or umlaut mark
-
- # Some extra Latin 1 chars that are listed in the HTML3.2 draft (21-May-96)
- copy   => '©',  # copyright sign
- reg    => '®',  # registered sign
- nbsp   => "\240", # non breaking space
-
- # Additional ISO-8859/1 entities listed in rfc1866 (section 14)
- iexcl  => '¡',
- cent   => '¢',
- pound  => '£',
- curren => '¤',
- yen    => '¥',
- brvbar => '¦',
- sect   => '§',
- uml    => '¨',
- ordf   => 'ª',
- laquo  => '«',
-'not'   => '¬',    # not is a keyword in perl
- shy    => '­',
- macr   => '¯',
- deg    => '°',
- plusmn => '±',
- sup1   => '¹',
- sup2   => '²',
- sup3   => '³',
- acute  => '´',
- micro  => 'µ',
- para   => '¶',
- middot => '·',
- cedil  => '¸',
- ordm   => 'º',
- raquo  => '»',
- frac14 => '¼',
- frac12 => '½',
- frac34 => '¾',
- iquest => '¿',
-'times' => '×',    # times is a keyword in perl
- divide => '÷',
-
-# some POD special entities
- verbar => '|',
- sol => '/'
-);
+use Exporter 'import';
+use base qw/Pod::Simple::Methody/;
 
-##---------------------------------------------------------------------------
+our @EXPORT = qw(&podchecker);
 
 ##---------------------------------
 ## Function definitions begin here
@@ -522,7 +391,7 @@ sub podchecker {
     $outfile ||= \*STDERR;
 
     ## Now create a pod checker
-    my $checker = new Pod::Checker(%options);
+    my $checker = Pod::Checker->new(%options);
 
     ## Now check the pod document for errors
     $checker->parse_from_file($infile, $outfile);
@@ -531,6 +400,7 @@ sub podchecker {
     return $checker->num_errors();
 }
 
+
 ##---------------------------------------------------------------------------
 
 ##-------------------------------
@@ -544,7 +414,7 @@ sub podchecker {
 =item C<Pod::Checker-E<gt>new( %options )>
 
 Return a reference to a new Pod::Checker object that inherits from
-Pod::Parser and is used for calling the required methods later. The
+Pod::Simple and is used for calling the required methods later. The
 following options are recognized:
 
 C<-warnings =E<gt> num>
@@ -558,35 +428,41 @@ POD formatters.
 
 =cut
 
-## sub new {
-##     my $this = shift;
-##     my $class = ref($this) || $this;
-##     my %params = @_;
-##     my $self = {%params};
-##     bless $self, $class;
-##     $self->initialize();
-##     return $self;
-## }
-
-sub initialize {
-    my $self = shift;
-    ## Initialize number of errors, and setup an error function to
-    ## increment this number and then print to the designated output.
-    $self->{_NUM_ERRORS} = 0;
-    $self->{_NUM_WARNINGS} = 0;
-    $self->{-quiet} ||= 0;
-    # set the error handling subroutine
-    $self->errorsub($self->{-quiet} ? sub { 1; } : 'poderror');
-    $self->{_commands} = 0; # total number of POD commands encountered
-    $self->{_list_stack} = []; # stack for nested lists
-    $self->{_have_begin} = ''; # stores =begin
-    $self->{_links} = []; # stack for internal hyperlinks
-    $self->{_nodes} = []; # stack for =head/=item nodes
-    $self->{_index} = []; # text in X<>
-    # print warnings?
-    $self->{-warnings} = 1 unless(defined $self->{-warnings});
-    $self->{_current_head1} = ''; # the current =head1 block
-    $self->parseopts(-process_cut_cmd => 1, -warnings => $self->{-warnings});
+sub new {
+    my $new = shift->SUPER::new(@_);
+    $new->{'output_fh'} ||= *STDERR{IO};
+
+    # Set options
+    my %opts = @_;
+    $new->{'-warnings'} = defined $opts{'-warnings'} ?
+                                  $opts{'-warnings'} : 1; # default on
+    $new->{'-quiet'} = $opts{'-quiet'} || 0; # default off
+
+    # Initialize number of errors/warnings
+    $new->{'_NUM_ERRORS'} = 0;
+    $new->{'_NUM_WARNINGS'} = 0;
+
+    # 'current' also means 'most recent' in the follow comments
+    $new->{'_thispara'} = '';       # current POD paragraph
+    $new->{'_line'} = 0;            # current line number
+    $new->{'_head_num'} = 0;        # current =head level (set to 0 to make
+                                    #   logic easier down the road)
+    $new->{'_cmds_since_head'} = 0; # num of POD directives since prev. =headN
+    $new->{'_nodes'} = [];          # stack for =head/=item nodes
+    $new->{'_fcode_stack'} = [];    # stack for nested formatting codes
+    $new->{'_fcode_pos'} = [];      # stack for position in paragraph of fcodes
+    $new->{'_begin_stack'} = [];    # stack for =begins: [line #, target]
+    $new->{'_links'} = [];          # stack for hyperlinks to external entities
+    $new->{'_internal_links'} = []; # set of linked-to internal sections
+    $new->{'_index'} = [];          # stack for text in X<>s
+
+    $new->accept_targets('*'); # check all =begin/=for blocks
+    $new->cut_handler( \&handle_pod_and_cut ); # warn if text after =cut
+    $new->pod_handler( \&handle_pod_and_cut ); # warn if text after =pod
+    $new->whiteline_handler( \&handle_whiteline ); # warn if whiteline
+    $new->parse_empty_lists(1); # warn if they are empty
+
+    return $new;
 }
 
 ##################################
@@ -595,9 +471,9 @@ sub initialize {
 
 =item C<$checker-E<gt>poderror( {%opts}, @args )>
 
-Internal method for printing errors and warnings. If no options are
-given, simply prints "@_". The following options are recognized and used
-to form the output:
+Internal method for printing errors and warnings. If no options are given,
+simply prints "@_". The following options are recognized and used to form
+the output:
 
   -msg
 
@@ -609,7 +485,8 @@ The line number the error occurred in.
 
   -file
 
-The file (name) the error occurred in.
+The file (name) the error occurred in. Defaults to the name of the current
+file being processed.
 
   -severity
 
@@ -623,24 +500,28 @@ sub poderror {
     my %opts = (ref $_[0]) ? %{shift()} : ();
 
     ## Retrieve options
-    chomp( my $msg  = ($opts{-msg} || '')."@_" );
-    my $line = (exists $opts{-line}) ? " at line $opts{-line}" : '';
-    my $file = (exists $opts{-file}) ? " in file $opts{-file}" : '';
-    unless (exists $opts{-severity}) {
+    chomp( my $msg  = ($opts{'-msg'} || '')."@_" );
+    my $line = (exists $opts{'-line'}) ? " at line $opts{'-line'}" : '';
+    my $file = ' in file ' . ((exists $opts{'-file'})
+                              ? $opts{'-file'}
+                              : ((defined $self->source_filename)
+                                 ? $self->source_filename
+                                 : "???"));
+    unless (exists $opts{'-severity'}) {
        ## See if can find severity in message prefix
-       $opts{-severity} = $1  if ( $msg =~ s/^\**\s*([A-Z]{3,}):\s+// );
+       $opts{'-severity'} = $1  if ( $msg =~ s/^\**\s*([A-Z]{3,}):\s+// );
     }
-    my $severity = (exists $opts{-severity}) ? "*** $opts{-severity}: " : '';
+    my $severity = (exists $opts{'-severity'}) ? "*** $opts{-severity}: " : '';
 
     ## Increment error count and print message "
-    ++($self->{_NUM_ERRORS})
-        if(!%opts || ($opts{-severity} && $opts{-severity} eq 'ERROR'));
-    ++($self->{_NUM_WARNINGS})
-        if(!%opts || ($opts{-severity} && $opts{-severity} eq 'WARNING'));
-    unless($self->{-quiet}) {
-      my $out_fh = $self->output_handle() || \*STDERR;
+    ++($self->{'_NUM_ERRORS'})
+        if(!%opts || ($opts{-severity} && $opts{'-severity'} eq 'ERROR'));
+    ++($self->{'_NUM_WARNINGS'})
+        if(!%opts || ($opts{-severity} && $opts{'-severity'} eq 'WARNING'));
+    unless($self->{'-quiet'}) {
+      my $out_fh = $self->{'output_fh'} || \*STDERR;
       print $out_fh ($severity, $msg, $line, $file, "\n")
-        if($self->{-warnings} || !%opts || $opts{-severity} ne 'WARNING');
+        if($self->{'-warnings'} || !%opts || $opts{'-severity'} ne 'WARNING');
     }
 }
 
@@ -653,7 +534,7 @@ Set (if argument specified) and retrieve the number of errors found.
 =cut
 
 sub num_errors {
-   return (@_ > 1) ? ($_[0]->{_NUM_ERRORS} = $_[1]) : $_[0]->{_NUM_ERRORS};
+   return (@_ > 1) ? ($_[0]->{'_NUM_ERRORS'} = $_[1]) : $_[0]->{'_NUM_ERRORS'};
 }
 
 ##################################
@@ -665,7 +546,8 @@ Set (if argument specified) and retrieve the number of warnings found.
 =cut
 
 sub num_warnings {
-   return (@_ > 1) ? ($_[0]->{_NUM_WARNINGS} = $_[1]) : $_[0]->{_NUM_WARNINGS};
+   return (@_ > 1) ? ($_[0]->{'_NUM_WARNINGS'} = $_[1]) :
+                      $_[0]->{'_NUM_WARNINGS'};
 }
 
 ##################################
@@ -679,7 +561,7 @@ found in the C<=head1 NAME> section.
 
 sub name {
     return (@_ > 1 && $_[1]) ?
-        ($_[0]->{-name} = $_[1]) : $_[0]->{-name};
+        ($_[0]->{'_pod_name'} = $_[1]) : $_[0]->{'_pod_name'};
 }
 
 ##################################
@@ -699,12 +581,12 @@ sub node {
         $text =~ s/\s+$//s; # strip trailing whitespace
         $text =~ s/\s+/ /gs; # collapse whitespace
         # add node, order important!
-        push(@{$self->{_nodes}}, $text);
+        push(@{$self->{'_nodes'}}, $text);
         # keep also a uniqueness counter
-        $self->{_unique_nodes}->{$text}++ if($text !~ /^\s*$/s);
+        $self->{'_unique_nodes'}->{$text}++ if($text !~ /^\s*$/s);
         return $text;
     }
-    @{$self->{_nodes}};
+    @{$self->{'_nodes'}};
 }
 
 ##################################
@@ -724,58 +606,270 @@ sub idx {
         $text =~ s/\s+$//s; # strip trailing whitespace
         $text =~ s/\s+/ /gs; # collapse whitespace
         # add node, order important!
-        push(@{$self->{_index}}, $text);
+        push(@{$self->{'_index'}}, $text);
         # keep also a uniqueness counter
-        $self->{_unique_nodes}->{$text}++ if($text !~ /^\s*$/s);
+        $self->{'_unique_nodes'}->{$text}++ if($text !~ /^\s*$/s);
         return $text;
     }
-    @{$self->{_index}};
+    @{$self->{'_index'}};
 }
 
 ##################################
 
-=item C<$checker-E<gt>hyperlink()>
+# add a hyperlink to the list of those of the current POD; returns current
+# list after the addition has been done
+sub hyperlink {
+    my $self = shift;
+    push(@{$self->{'_links'}}, $_[0]);
+    return $_[0];
+}
 
-Add (if argument specified) and retrieve the hyperlinks (as defined by
-C<LE<lt>E<gt>>) of the current POD. They consist of a 2-item array: line
-number and C<Pod::Hyperlink> object.
+=item C<$checker-E<gt>hyperlinks()>
 
-=back
+Retrieve an array containing the hyperlinks to things outside
+the current POD (as defined by C<LE<lt>E<gt>>).
+
+Each is an instance of a class with the following methods:
 
 =cut
 
-# set/return hyperlinks of the current POD
-sub hyperlink {
-    my $self = shift;
-    if($_[0]) {
-        push(@{$self->{_links}}, $_[0]);
-        return $_[0];
+sub hyperlinks {
+    @{shift->{'_links'}};
+}
+
+##################################
+
+# override Pod::Simple's whine() and scream() to use poderror()
+
+# Note:
+# Ignore $self->{'no_whining'} b/c $self->{'quiet'} takes care of it in poderror
+# Don't bother incrementing $self->{'errors_seen'} -- it's not used
+# Don't bother pushing to $self->{'errata'} b/c poderror() outputs immediately
+# We don't need to set $self->no_errata_section(1) b/c of these overrides
+
+
+sub whine {
+    my ($self, $line, $complaint) = @_;
+
+    my $severity = 'ERROR';
+
+    if (0) {
+      # XXX: Let's standardize what's a warning and what's an error.  Let's not
+      # move stuff up and down the severity tree.  -- rjbs, 2013-04-12
+      # Convert errors in Pod::Simple that are warnings in Pod::Checker
+      # XXX Do differently so the $complaint can be reworded without this breaking
+      $severity = 'WARNING' if
+          $complaint =~ /^Expected '=item .+?'$/ ||
+          $complaint =~ /^You can't have =items \(as at line .+?\) unless the first thing after the =over is an =item$/ ||
+          $complaint =~ /^You have '=item .+?' instead of the expected '=item .+?'$/;
+    }
+
+    $self->poderror({ -line => $line,
+                      -severity => $severity,
+                      -msg => $complaint });
+
+    return 1; # assume everything is peachy keen
+}
+
+sub scream {
+    my ($self, $line, $complaint) = @_;
+
+    $self->poderror({ -line => $line,
+                      -severity => 'ERROR', # consider making severity 'FATAL'
+                      -msg => $complaint });
+
+    return 1;
+}
+
+
+##################################
+
+# Some helper subroutines
+
+sub _init_event { # assignments done at the start of most events
+    $_[0]{'_thispara'} = '';
+    $_[0]{'_line'} = $_[1]{'start_line'};
+    $_[0]{'_cmds_since_head'}++;
+}
+
+sub _check_fcode {
+    my ($self, $inner, $outers) = @_;
+    # Check for an fcode inside another of the same fcode
+    # XXX line number is the line of the start of the paragraph that the warning
+    # is in, not the line that the warning is on. Fix this
+
+    # Later versions of Pod::Simple forbid nested L<>'s
+    return if $inner eq 'L' && $Pod::Simple::VERSION ge '3.33';
+
+    if (grep { $_ eq $inner } @$outers) {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => "nested commands $inner<...$inner<...>...>"});
+    }
+}
+
+##################################
+
+sub handle_text { $_[0]{'_thispara'} .= $_[1] }
+
+# whiteline is a seemingly blank line that matches /[^\S\r\n]/
+sub handle_whiteline {
+    my ($line, $line_n, $self) = @_;
+    $self->poderror({
+        -line => $line_n,
+        -severity => 'WARNING',
+        -msg => 'line containing nothing but whitespace in paragraph'});
+}
+
+######## Directives
+sub handle_pod_and_cut {
+    my ($line, $line_n, $self) = @_;
+    $self->{'_cmds_since_head'}++;
+    if ($line =~ /=(pod|cut)\s+\S/) {
+        $self->poderror({ -line => $line_n,
+                          -severity => 'ERROR',
+                          -msg => "Spurious text after =$1"});
     }
-    @{$self->{_links}};
 }
 
-## overrides for Pod::Parser
-
-sub end_pod {
-    ## Do some final checks and
-    ## print the number of errors found
-    my $self   = shift;
-    my $infile = $self->input_file();
-
-    if(@{$self->{_list_stack}}) {
-        my $list;
-        while(($list = $self->_close_list('EOF',$infile)) &&
-          $list->indent() ne 'auto') {
-            $self->poderror({ -line => 'EOF', -file => $infile,
-                -severity => 'ERROR', -msg => '=over on line ' .
-                $list->start() . ' without closing =back' });
+sub start_Para { shift->_init_event(@_); }
+sub end_Para   {
+    my $self = shift;
+    # Get the NAME of the pod document
+    if ($self->{'_head_num'} == 1 && $self->{'_head_text'} eq 'NAME') {
+        if ($self->{'_thispara'} =~ /^\s*(\S+?)\s*[,-]/) {
+            $self->{'_pod_name'} = $1 unless defined $self->{'_pod_name'};
         }
     }
+}
+
+sub start_Verbatim {
+    my $self = shift;
+    $self->_init_event(@_);
+
+    if ($self->{'_head_num'} == 1 && $self->{'_head_text'} eq 'NAME') {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => 'Verbatim paragraph in NAME section' });
+    }
+}
+# Don't need an end_Verbatim
+
+# Do I need to do anything else with this?
+sub start_Data { shift->_init_event() }
+
+sub start_head1 { shift->start_head(1, @_) }
+sub start_head2 { shift->start_head(2, @_) }
+sub start_head3 { shift->start_head(3, @_) }
+sub start_head4 { shift->start_head(4, @_) }
+sub start_head  {
+    my $self = shift;
+    my $h = shift;
+    $self->_init_event(@_);
+    my $prev_h = $self->{'_head_num'};
+    $self->{'_head_num'} = $h;
+    $self->{"_count_head$h"}++;
+
+    if ($h > 1 && !$self->{'_count_head'.($h-1)}) {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => "=head$h without preceding higher level"});
+    }
+
+    # If this is the first =head of the doc, $prev_h is 0, thus less than $h
+    if ($self->{'_cmds_since_head'} == 1 && $prev_h >= $h) {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => 'empty section in previous paragraph'});
+    }
+}
+
+sub end_head1 { shift->end_head(@_) }
+sub end_head2 { shift->end_head(@_) }
+sub end_head3 { shift->end_head(@_) }
+sub end_head4 { shift->end_head(@_) }
+sub end_head  {
+    my $self = shift;
+    my $arg = $self->{'_thispara'};
+    $arg =~ s/\s+$//;
+    $self->{'_head_text'} = $arg;
+    $self->{'_cmds_since_head'} = 0;
+    my $h = $self->{'_head_num'};
+    $self->node($arg); # remember this node
+    if ($arg eq '') {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'ERROR',
+                          -msg => "empty =head$h" });
+    }
+}
+
+sub start_over_bullet { shift->start_over(@_, 'bullet') }
+sub start_over_number { shift->start_over(@_, 'number') }
+sub start_over_text   { shift->start_over(@_, 'definition') }
+sub start_over_block  { shift->start_over(@_, 'block') }
+sub start_over_empty  {
+    my $self = shift;
+    $self->start_over(@_, 'empty');
+    $self->poderror({ -line => $self->{'_line'},
+                      -severity => 'WARNING',
+                      -msg => 'empty =over/=back block' });
+}
+sub start_over {
+    my $self = shift;
+    my $type = pop;
+    $self->_init_event(@_);
+}
+
+sub start_item_bullet { shift->_init_event(@_) }
+sub start_item_number { shift->_init_event(@_) }
+sub start_item_text   { shift->_init_event(@_) }
+sub end_item_bullet { shift->end_item('bullet') }
+sub end_item_number { shift->end_item('number') }
+sub end_item_text   { shift->end_item('definition') }
+sub end_item {
+    my $self = shift;
+    my $type = shift;
+    # If there is verbatim text in this item, it will show up as part of
+    # 'paras', and not part of '_thispara'.  If the first para after this is a
+    # verbatim one, it actually will be (part of) the contents for this item.
+    if (   $self->{'_thispara'} eq ''
+        && (  ! @{$self->{'paras'}}
+            ||    $self->{'paras'}[0][0] !~ /Verbatim/i))
+    {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => '=item has no contents' });
+    }
+
+    $self->node($self->{'_thispara'}); # remember this node
+}
+
+sub start_for { # =for and =begin directives
+    my ($self, $flags) = @_;
+    $self->_init_event($flags);
+    push @{$self->{'_begin_stack'}}, [$self->{'_line'}, $flags->{'target'}];
+}
+
+sub end_for {
+    my ($self, $flags) = @_;
+    my ($line, $target) = @{pop @{$self->{'_begin_stack'}}};
+    if ($flags->{'fake-closer'}) { # meaning Pod::Simple generated this =end
+        $self->poderror({ -line => $line,
+                          -severity => 'ERROR',
+                          -msg => "=begin $target without matching =end $target"
+                        });
+    }
+}
+
+sub end_Document {
+    # Some final error checks
+    my $self = shift;
+
+    # no POD found here
+    $self->num_errors(-1) && return unless $self->content_seen;
 
-    # check validity of document internal hyperlinks
-    # first build the node names from the paragraph text
     my %nodes;
-    foreach($self->node()) {
+    for ($self->node()) {
         $nodes{$_} = 1;
         if(/^(\S+)\s+\S/) {
             # we have more than one word. Use the first as a node, too.
@@ -783,548 +877,215 @@ sub end_pod {
             $nodes{$1} ||= 2; # derived node
         }
     }
-    foreach($self->idx()) {
+    for ($self->idx()) {
         $nodes{$_} = 3; # index node
     }
-    foreach($self->hyperlink()) {
-        my ($line,$link) = @$_;
-        # _TODO_ what if there is a link to the page itself by the name,
-        # e.g. in Tk::Pod : L<Tk::Pod/"DESCRIPTION">
-        if($link->node() && !$link->page() && $link->type() ne 'hyperlink') {
-            my $node = $self->_check_ptree($self->parse_text($link->node(),
-                $line), $line, $infile, 'L');
-            if($node && !$nodes{$node}) {
-                $self->poderror({ -line => $line || '', -file => $infile,
-                    -severity => 'ERROR',
-                    -msg => "unresolved internal link '$node'"});
-            }
+
+    # XXX update unresolved internal link POD -- single word not enclosed in ""?
+    # I don't know what I was thinking when I made the above TODO, and I don't
+    # know what it means...
+
+    for my $link (@{ $self->{'_internal_links'} }) {
+        my ($name, $line) = @$link;
+        unless ( $nodes{$name} ) {
+            $self->poderror({ -line => $line,
+                              -severity => 'ERROR',
+                              -msg => "unresolved internal link '$name'"});
         }
     }
 
     # check the internal nodes for uniqueness. This pertains to
     # =headX, =item and X<...>
-    if($self->{-warnings} && $self->{-warnings}>1) {
-      foreach(grep($self->{_unique_nodes}->{$_} > 1,
-        keys %{$self->{_unique_nodes}})) {
-          $self->poderror({ -line => '-', -file => $infile,
-            -severity => 'WARNING',
-            -msg => "multiple occurrence of link target '$_'"});
-      }
-    }
-
-    # no POD found here
-    $self->num_errors(-1) if($self->{_commands} == 0);
-}
-
-# check a POD command directive
-sub command {
-    my ($self, $cmd, $paragraph, $line_num, $pod_para) = @_;
-    my ($file, $line) = $pod_para->file_line;
-    ## Check the command syntax
-    my $arg; # this will hold the command argument
-    if (! $VALID_COMMANDS{$cmd}) {
-       $self->poderror({ -line => $line, -file => $file, -severity => 'ERROR',
-                         -msg => "Unknown command '$cmd'" });
-    }
-    else { # found a valid command
-        $self->{_commands}++; # delete this line if below is enabled again
-
-       $self->_commands_in_paragraphs($paragraph, $pod_para);
-
-        ##### following check disabled due to strong request
-        #if(!$self->{_commands}++ && $cmd !~ /^head/) {
-        #    $self->poderror({ -line => $line, -file => $file,
-        #         -severity => 'WARNING',
-        #         -msg => "file does not start with =head" });
-        #}
-
-        # check syntax of particular command
-        if($cmd eq 'over') {
-            # check for argument
-            $arg = $self->interpolate_and_check($paragraph, $line,$file);
-            my $indent = 4; # default
-            if($arg && $arg =~ /^\s*(\d+)\s*$/) {
-                $indent = $1;
-            }
-            # start a new list
-            $self->_open_list($indent,$line,$file);
-        }
-        elsif($cmd eq 'item') {
-            # are we in a list?
-            unless(@{$self->{_list_stack}}) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'ERROR',
-                     -msg => '=item without previous =over' });
-                # auto-open in case we encounter many more
-                $self->_open_list('auto',$line,$file);
-            }
-            my $list = $self->{_list_stack}->[0];
-            # check whether the previous item had some contents
-            if(defined $self->{_list_item_contents} &&
-              $self->{_list_item_contents} == 0) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING',
-                     -msg => 'previous =item has no contents' });
-            }
-            if($list->{_has_par}) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING',
-                     -msg => 'preceding non-item paragraph(s)' });
-                delete $list->{_has_par};
-            }
-            # check for argument
-            $arg = $self->interpolate_and_check($paragraph, $line, $file);
-            if($arg && $arg =~ /(\S+)/) {
-                $arg =~ s/[\s\n]+$//;
-                my $type;
-                if($arg =~ /^[*]\s*(\S*.*)/) {
-                  $type = 'bullet';
-                  $self->{_list_item_contents} = $1 ? 1 : 0;
-                  $arg = $1;
-                }
-                elsif($arg =~ /^\d+\.?\s+(\S*)/) {
-                  $type = 'number';
-                  $self->{_list_item_contents} = $1 ? 1 : 0;
-                  $arg = $1;
-                }
-                else {
-                  $type = 'definition';
-                  $self->{_list_item_contents} = 1;
-                }
-                my $first = $list->type();
-                if($first && $first ne $type) {
-                    $self->poderror({ -line => $line, -file => $file,
-                       -severity => 'WARNING',
-                       -msg => "=item type mismatch ('$first' vs. '$type')"});
-                }
-                else { # first item
-                    $list->type($type);
-                }
-            }
-            else {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING',
-                     -msg => 'No argument for =item' });
-                $arg = ' '; # empty
-                $self->{_list_item_contents} = 0;
-            }
-            # add this item
-            $list->item($arg);
-            # remember this node
-            $self->node($arg);
-        }
-        elsif($cmd eq 'back') {
-            # check if we have an open list
-            unless(@{$self->{_list_stack}}) {
-                $self->poderror({ -line => $line, -file => $file,
-                         -severity => 'ERROR',
-                         -msg => '=back without previous =over' });
-            }
-            else {
-                # check for spurious characters
-                $arg = $self->interpolate_and_check($paragraph, $line,$file);
-                if($arg && $arg =~ /\S/) {
-                    $self->poderror({ -line => $line, -file => $file,
-                         -severity => 'ERROR',
-                         -msg => 'Spurious character(s) after =back' });
-                }
-                # close list
-                my $list = $self->_close_list($line,$file);
-                # check for empty lists
-                if(!$list->item() && $self->{-warnings}) {
-                    $self->poderror({ -line => $line, -file => $file,
-                         -severity => 'WARNING',
-                         -msg => 'No items in =over (at line ' .
-                         $list->start() . ') / =back list'});
-                }
-            }
-        }
-        elsif($cmd =~ /^head(\d+)/) {
-            my $hnum = $1;
-            $self->{"_have_head_$hnum"}++; # count head types
-            if($hnum > 1 && !$self->{'_have_head_'.($hnum -1)}) {
-              $self->poderror({ -line => $line, -file => $file,
-                   -severity => 'WARNING',
-                   -msg => "=head$hnum without preceding higher level"});
-            }
-            # check whether the previous =head section had some contents
-            if(defined $self->{_commands_in_head} &&
-              $self->{_commands_in_head} == 0 &&
-              defined $self->{_last_head} &&
-              $self->{_last_head} >= $hnum) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING',
-                     -msg => 'empty section in previous paragraph'});
-            }
-            $self->{_commands_in_head} = -1;
-            $self->{_last_head} = $hnum;
-            # check if there is an open list
-            if(@{$self->{_list_stack}}) {
-                my $list;
-                while(($list = $self->_close_list($line,$file)) &&
-                  $list->indent() ne 'auto') {
-                    $self->poderror({ -line => $line, -file => $file,
-                         -severity => 'ERROR',
-                         -msg => '=over on line '. $list->start() .
-                         " without closing =back (at $cmd)" });
-                }
-            }
-            # remember this node
-            $arg = $self->interpolate_and_check($paragraph, $line,$file);
-            $arg =~ s/[\s\n]+$//s;
-            $self->node($arg);
-            unless(length($arg)) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'ERROR',
-                     -msg => "empty =$cmd"});
-            }
-            if($cmd eq 'head1') {
-                $self->{_current_head1} = $arg;
-            } else {
-                $self->{_current_head1} = '';
-            }
-        }
-        elsif($cmd eq 'begin') {
-            if($self->{_have_begin}) {
-                # already have a begin
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'ERROR',
-                     -msg => q{Nested =begin's (first at line } .
-                     $self->{_have_begin} . ')'});
-            }
-            else {
-                # check for argument
-                $arg = $self->interpolate_and_check($paragraph, $line,$file);
-                unless($arg && $arg =~ /(\S+)/) {
-                    $self->poderror({ -line => $line, -file => $file,
-                         -severity => 'ERROR',
-                         -msg => 'No argument for =begin'});
-                }
-                # remember the =begin
-                $self->{_have_begin} = "$line:$1";
-            }
-        }
-        elsif($cmd eq 'end') {
-            if($self->{_have_begin}) {
-                # close the existing =begin
-                $self->{_have_begin} = '';
-                # check for spurious characters
-                $arg = $self->interpolate_and_check($paragraph, $line,$file);
-                # the closing argument is optional
-                #if($arg && $arg =~ /\S/) {
-                #    $self->poderror({ -line => $line, -file => $file,
-                #         -severity => 'WARNING',
-                #         -msg => "Spurious character(s) after =end" });
-                #}
-            }
-            else {
-                # don't have a matching =begin
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'ERROR',
-                     -msg => '=end without =begin' });
-            }
-        }
-        elsif($cmd eq 'for') {
-            unless($paragraph =~ /\s*(\S+)\s*/) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'ERROR',
-                     -msg => '=for without formatter specification' });
-            }
-            $arg = ''; # do not expand paragraph below
-        }
-        elsif($cmd =~ /^(pod|cut)$/) {
-            # check for argument
-            $arg = $self->interpolate_and_check($paragraph, $line,$file);
-            if($arg && $arg =~ /(\S+)/) {
-                $self->poderror({ -line => $line, -file => $file,
-                      -severity => 'ERROR',
-                      -msg => "Spurious text after =$cmd"});
+    if ($self->{'-warnings'} > 1 ) {
+        for my $node (sort keys %{ $self->{'_unique_nodes'} }) {
+            my $count = $self->{'_unique_nodes'}{$node};
+            if ($count > 1) { # not unique
+                $self->poderror({
+                    -line => '-',
+                    -severity => 'WARNING',
+                    -msg => "multiple occurrences ($count) of link target ".
+                        "'$node'"});
             }
-           if($cmd eq 'cut' && (!$self->{_PREVIOUS} || $self->{_PREVIOUS} eq 'cut')) {
-                $self->poderror({ -line => $line, -file => $file,
-                      -severity => 'ERROR',
-                      -msg => "Spurious =cut command"});
-           }
-           if($cmd eq 'pod' && $self->{_PREVIOUS} && $self->{_PREVIOUS} ne 'cut') {
-                $self->poderror({ -line => $line, -file => $file,
-                      -severity => 'ERROR',
-                      -msg => "Spurious =pod command"});
-           }
         }
-    $self->{_commands_in_head}++;
-    ## Check the interior sequences in the command-text
-    $self->interpolate_and_check($paragraph, $line,$file)
-        unless(defined $arg);
     }
 }
 
-sub _open_list
-{
-    my ($self,$indent,$line,$file) = @_;
-    my $list = Pod::List->new(
-           -indent => $indent,
-           -start => $line,
-           -file => $file);
-    unshift(@{$self->{_list_stack}}, $list);
-    undef $self->{_list_item_contents};
-    $list;
-}
+########  Formatting codes
 
-sub _close_list
-{
-    my ($self,$line,$file) = @_;
-    my $list = shift(@{$self->{_list_stack}});
-    if(defined $self->{_list_item_contents} &&
-      $self->{_list_item_contents} == 0) {
-        $self->poderror({ -line => $line, -file => $file,
-            -severity => 'WARNING',
-            -msg => 'previous =item has no contents' });
-    }
-    undef $self->{_list_item_contents};
-    $list;
+sub start_B { shift->start_fcode('B') }
+sub start_C { shift->start_fcode('C') }
+sub start_F { shift->start_fcode('F') }
+sub start_I { shift->start_fcode('I') }
+sub start_S { shift->start_fcode('S') }
+sub start_fcode {
+    my ($self, $fcode) = @_;
+    unshift @{$self->{'_fcode_stack'}}, $fcode;
 }
 
-# process a block of some text
-sub interpolate_and_check {
-    my ($self, $paragraph, $line, $file) = @_;
-    ## Check the interior sequences in the command-text
-    # and return the text
-    $self->_check_ptree(
-        $self->parse_text($paragraph,$line), $line, $file, '');
+sub end_B { shift->end_fcode() }
+sub end_C { shift->end_fcode() }
+sub end_F { shift->end_fcode() }
+sub end_I { shift->end_fcode() }
+sub end_S { shift->end_fcode() }
+sub end_fcode {
+    my $self = shift;
+    $self->_check_fcode(shift @{$self->{'_fcode_stack'}}, # current fcode removed
+                        $self->{'_fcode_stack'}); # previous fcodes
 }
 
-sub _check_ptree {
-    my ($self,$ptree,$line,$file,$nestlist) = @_;
-    local($_);
-    my $text = '';
-    # process each node in the parse tree
-    foreach(@$ptree) {
-        # regular text chunk
-        unless(ref) {
-            # count the unescaped angle brackets
-            # complain only when warning level is greater than 1
-            if($self->{-warnings} && $self->{-warnings}>1) {
-              my $count;
-              if($count = tr/<>/<>/) {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING',
-                     -msg => "$count unescaped <> in paragraph" });
-                }
-            }
-            $text .= $_;
-            next;
-        }
-        # have an interior sequence
-        my $cmd = $_->cmd_name();
-        my $contents = $_->parse_tree();
-        ($file,$line) = $_->file_line();
-        # check for valid tag
-        if (! $VALID_SEQUENCES{$cmd}) {
-            $self->poderror({ -line => $line, -file => $file,
-                 -severity => 'ERROR',
-                 -msg => qq(Unknown interior-sequence '$cmd')});
-            # expand it anyway
-            $text .= $self->_check_ptree($contents, $line, $file, "$nestlist$cmd");
-            next;
-        }
-        if(index($nestlist, $cmd) != -1) {
-            $self->poderror({ -line => $line, -file => $file,
-                 -severity => 'WARNING',
-                 -msg => "nested commands $cmd<...$cmd<...>...>"});
-            # _TODO_ should we add the contents anyway?
-            # expand it anyway, see below
-        }
-        if($cmd eq 'E') {
-            # preserve entities
-            if(@$contents > 1 || ref $$contents[0] || $$contents[0] !~ /^\w+$/) {
-                $self->poderror({ -line => $line, -file => $file,
-                    -severity => 'ERROR',
-                    -msg => 'garbled entity ' . $_->raw_text()});
-                next;
-            }
-            my $ent = $$contents[0];
-            my $val;
-            if($ent =~ /^0x[0-9a-f]+$/i) {
-                # hexadec entity
-                $val = hex($ent);
-            }
-            elsif($ent =~ /^0\d+$/) {
-                # octal
-                $val = oct($ent);
-            }
-            elsif($ent =~ /^\d+$/) {
-                # numeric entity
-                $val = $ent;
-            }
-            if(defined $val) {
-                if($val>0 && $val<256) {
-                    $text .= chr($val);
-                }
-                else {
-                    $self->poderror({ -line => $line, -file => $file,
-                        -severity => 'ERROR',
-                        -msg => 'Entity number out of range ' . $_->raw_text()});
-                }
-            }
-            elsif($ENTITIES{$ent}) {
-                # known ISO entity
-                $text .= $ENTITIES{$ent};
-            }
-            else {
-                $self->poderror({ -line => $line, -file => $file,
-                    -severity => 'WARNING',
-                    -msg => 'Unknown entity ' . $_->raw_text()});
-                $text .= "E<$ent>";
-            }
-        }
-        elsif($cmd eq 'L') {
-            # try to parse the hyperlink
-            my $link = Pod::Hyperlink->new($contents->raw_text());
-            unless(defined $link) {
-                $self->poderror({ -line => $line, -file => $file,
-                    -severity => 'ERROR',
-                    -msg => 'malformed link ' . $_->raw_text() ." : $@"});
-                next;
-            }
-            $link->line($line); # remember line
-            if($self->{-warnings}) {
-                foreach my $w ($link->warning()) {
-                    $self->poderror({ -line => $line, -file => $file,
-                        -severity => 'WARNING',
-                        -msg => $w });
-                }
-            }
-            # check the link text
-            $text .= $self->_check_ptree($self->parse_text($link->text(),
-                $line), $line, $file, "$nestlist$cmd");
-            # remember link
-            $self->hyperlink([$line,$link]);
-        }
-        elsif($cmd =~ /[BCFIS]/) {
-            # add the guts
-            $text .= $self->_check_ptree($contents, $line, $file, "$nestlist$cmd");
-        }
-        elsif($cmd eq 'Z') {
-            if(length($contents->raw_text())) {
-                $self->poderror({ -line => $line, -file => $file,
-                    -severity => 'ERROR',
-                    -msg => 'Nonempty Z<>'});
-            }
-        }
-        elsif($cmd eq 'X') {
-            my $idx = $self->_check_ptree($contents, $line, $file, "$nestlist$cmd");
-            if($idx =~ /^\s*$/s) {
-                $self->poderror({ -line => $line, -file => $file,
-                    -severity => 'ERROR',
-                    -msg => 'Empty X<>'});
-            }
-            else {
-                # remember this node
-                $self->idx($idx);
-            }
+sub start_L {
+    my ($self, $flags) = @_;
+    $self->start_fcode('L');
+
+    my $link = Pod::Checker::Hyperlink->new($flags, $self);
+    if ($link) {
+        if (   $link->type eq 'pod'
+            && $link->node
+                # It's an internal-to-this-page link if no page is given, or
+                # if the given one is to our NAME.
+            && (! $link->page || (   $self->{'_pod_name'}
+                                  && $link->page eq $self->{'_pod_name'})))
+        {
+            push @{ $self->{'_internal_links'} }, [ $link->{'-raw_node'}, $link->line ];
         }
         else {
-            # not reached
-            croak 'internal error';
+            $self->hyperlink($link);
         }
     }
-    $text;
 }
 
-# process a block of verbatim text
-sub verbatim {
-    ## Nothing particular to check
-    my ($self, $paragraph, $line_num, $pod_para) = @_;
-
-    $self->_preproc_par($paragraph);
-    $self->_commands_in_paragraphs($paragraph, $pod_para);
+sub end_L {
+    my $self = shift;
+    $self->end_fcode();
+}
 
-    if($self->{_current_head1} eq 'NAME') {
-        my ($file, $line) = $pod_para->file_line;
-        $self->poderror({ -line => $line, -file => $file,
-            -severity => 'WARNING',
-            -msg => 'Verbatim paragraph in NAME section' });
+sub start_X {
+    my $self = shift;
+    $self->start_fcode('X');
+    # keep track of where X<> starts in the paragraph
+    # (this is a stack so nested X<>s are handled correctly)
+    push @{$self->{'_fcode_pos'}}, length $self->{'_thispara'};
+}
+sub end_X {
+    my $self = shift;
+    # extract contents of X<> and replace with ''
+    my $start = pop @{$self->{'_fcode_pos'}}; # start at the beginning of X<>
+    my $end = length($self->{'_thispara'}) - $start; # end at end of X<>
+    my $x = substr($self->{'_thispara'}, $start, $end, '');
+    if ($x eq "") {
+        $self->poderror({ -line => $self->{'_line'},
+                          -severity => 'ERROR',
+                          -msg => "An empty X<>" });
     }
+    $self->idx($x); # remember this node
+    $self->end_fcode();
 }
 
-# process a block of regular text
-sub textblock {
-    my ($self, $paragraph, $line_num, $pod_para) = @_;
-    my ($file, $line) = $pod_para->file_line;
-
-    $self->_preproc_par($paragraph);
-    $self->_commands_in_paragraphs($paragraph, $pod_para);
-
-    # skip this paragraph if in a =begin block
-    unless($self->{_have_begin}) {
-        my $block = $self->interpolate_and_check($paragraph, $line,$file);
-        if($self->{_current_head1} eq 'NAME') {
-            if($block =~ /^\s*(\S+?)\s*[,-]/) {
-                # this is the canonical name
-                $self->{-name} = $1 unless(defined $self->{-name});
-            }
-        }
+package Pod::Checker::Hyperlink;
+
+# This class is used to represent L<> link structures, so that the individual
+# elements are easily accessible.  It is based on code in Pod::Hyperlink
+
+sub new {
+    my ($class,
+        $simple_link,   # The link structure returned by Pod::Simple
+        $caller         # The caller class
+    ) = @_;
+
+    my $self = +{};
+    bless $self, $class;
+
+    $self->{'-line'} ||= $caller->{'_line'};
+    $self->{'-type'} ||= $simple_link->{'type'};
+
+    # Force stringification of page and node.  (This expands any E<>.)
+    $self->{'-page'} = exists $simple_link->{'to'} ? "$simple_link->{'to'}" : "";
+    $self->{'-node'} = exists $simple_link->{'section'} ? "$simple_link->{'section'}" : "";
+
+    # Save the unmodified node text, as the .t files are expecting the message
+    # for internal link failures to include it (hence this preserves backward
+    # compatibility).
+    $self->{'-raw_node'} = $self->{'-node'};
+
+    # Remove leading/trailing white space.  Pod::Simple already warns about
+    # these, so if the only error is this, and the link is otherwise correct,
+    # only the Pod::Simple warning will be output, avoiding unnecessary
+    # confusion.
+    $self->{'-page'} =~ s/ ^ \s+ //x;
+    $self->{'-page'} =~ s/ \s+ $ //x;
+
+    $self->{'-node'} =~ s/ ^ \s+ //x;
+    $self->{'-node'} =~ s/ \s+ $ //x;
+
+    # Pod::Simple warns about L<> and L< >, but not L</>
+    if ($self->{'-page'} eq "" && $self->{'-node'} eq "") {
+        $caller->poderror({ -line => $caller->{'_line'},
+                          -severity => 'WARNING',
+                          -msg => 'empty link'});
+        return;
     }
+
+    return $self;
 }
 
-sub _preproc_par
-{
-    my $self = shift;
-    $_[0] =~ s/[\s\n]+$//;
-    if($_[0]) {
-        $self->{_commands_in_head}++;
-        $self->{_list_item_contents}++ if(defined $self->{_list_item_contents});
-        if(@{$self->{_list_stack}} && !$self->{_list_stack}->[0]->item()) {
-            $self->{_list_stack}->[0]->{_has_par} = 1;
-        }
-    }
+=item line()
+
+Returns the approximate line number in which the link was encountered
+
+=cut
+
+sub line {
+    return $_[0]->{-line};
 }
 
-# look for =foo commands at the start of a line within a paragraph, as for
-# instance the following which prints as "* one =item two".
-#
-#     =item one
-#     =item two
-#
-# Examples of =foo written in docs are expected to be indented in a verbatim
-# or marked up C<=foo> so won't be caught.  A double-angle C<< =foo >> could
-# have the =foo at the start of a line, but that should be unlikely and is
-# easily enough dealt with by not putting a newline after the C<<.
-#
-sub _commands_in_paragraphs {
-  my ($self, $str, $pod_para) = @_;
-  while ($str =~ /[^\n]\n=([a-z][a-z0-9]+)/sg) {
-    my $cmd = $1;
-    my $pos = pos($str);
-    if ($VALID_COMMANDS{$cmd}) {
-      my ($file, $line) = $pod_para->file_line;
-      my $part = substr($str, 0, $pos);
-      $line += ($part =~ tr/\n//);  # count of newlines
-
-      $self->poderror
-        ({ -line => $line, -file => $file,
-           -severity => 'ERROR',
-           -msg => "Apparent command =$cmd not preceded by blank line"});
-    }
-  }
+=item type()
+
+Returns the type of the link; one of:
+C<"url"> for things like
+C<http://www.foo>, C<"man"> for man pages, or C<"pod">.
+
+=cut
+
+sub type {
+    return  $_[0]->{-type};
 }
 
-1;
+=item page()
 
-__END__
+Returns the linked-to page or url.
+
+=cut
+
+sub page {
+    return $_[0]->{-page};
+}
+
+=item node()
+
+Returns the anchor or node within the linked-to page, or an empty string
+(C<"">) if none appears in the link.
+
+=back
+
+=cut
+
+sub node {
+    return $_[0]->{-node};
+}
 
 =head1 AUTHOR
 
 Please report bugs using L<http://rt.cpan.org>.
 
 Brad Appleton E<lt>bradapp@enteract.comE<gt> (initial version),
-Marek Rouchal E<lt>marekr@cpan.orgE<gt>
+Marek Rouchal E<lt>marekr@cpan.orgE<gt>,
+Marc Green E<lt>marcgreen@cpan.orgE<gt> (port to Pod::Simple)
+Ricardo Signes E<lt>rjbs@cpan.orgE<gt> (more porting to Pod::Simple)
+Karl Williamson E<lt>khw@cpan.orgE<gt> (more porting to Pod::Simple)
 
 Based on code for B<Pod::Text::pod2text()> written by
 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 
-B<Pod::Checker> is part of the Pod-Checker distribution, and is based on
-L<Pod::Parser>.
-
 =cut
 
+1
index 75c316d..44bcfc5 100644 (file)
@@ -40,9 +40,8 @@ print OUT <<'!NO!SUBS!';
 # podchecker -- command to invoke the podchecker function in Pod::Checker
 #
 # Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved.
-# This file is part of "PodParser". PodParser is free software;
-# you can redistribute it and/or modify it under the same terms
-# as Perl itself.
+# This is free software; you can redistribute it and/or modify it under the
+# same terms as Perl itself.
 #############################################################################
 
 use strict;
@@ -110,7 +109,7 @@ results, call B<podchecker> with one single argument only.
 
 =head1 SEE ALSO
 
-L<Pod::Parser> and L<Pod::Checker>
+L<Pod::Simple> and L<Pod::Checker>
 
 =head1 AUTHORS
 
index 45ec573..4b942e9 100644 (file)
@@ -1 +1 @@
-*** ERROR: Unknown command 'encode' at line 20 in file t/pod/podchkenc.t
+*** ERROR: Unknown directive: =encode at line 20 in file t/pod/podchkenc.t
diff --git a/cpan/Pod-Checker/t/pod/podchklink.t b/cpan/Pod-Checker/t/pod/podchklink.t
new file mode 100644 (file)
index 0000000..ea6dfa7
--- /dev/null
@@ -0,0 +1,275 @@
+#!/usr/bin/perl
+
+# This tests Pod::Checker::Hyperlink
+
+use Test::More;
+use Pod::Checker;
+
+my @answers = (
+                {
+                 'line' => 12,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod'
+                },
+                {
+                 'line' => 14,
+                 'node' => 'section',
+                 'page' => '"manpage"',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 16,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 20,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 22,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 24,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 26,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 28,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                 'line' => 30,
+                 'node' => 'section',
+                 'page' => 'manpage',
+                 'type' => 'pod',
+                },
+                {
+                  'line' => 36,
+                  'node' => '',
+                  'page' => 'foo',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 38,
+                  'node' => '',
+                  'page' => 'bar',
+                  'type' => 'pod'
+                },
+                {
+                  'line' => 40,
+                  'node' => 'bar',
+                  'page' => 'foo',
+                  'type' => 'pod'
+                },
+                {
+                  'line' => 42,
+                  'node' => 'baz boo',
+                  'page' => 'foo',
+                  'type' => 'pod'
+                },
+                {
+                  'line' => 50,
+                  'node' => 'baz boo',
+                  'page' => 'foo bar',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 59,
+                  'node' => '',
+                  'page' => 'foobar',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 61,
+                  'node' => 'bar',
+                  'page' => 'foo',
+                  'type' => 'pod'
+                },
+                {
+                  'line' => 63,
+                  'node' => 'Italic text',
+                  'page' => 'foo',
+                  'type' => 'pod'
+                },
+                {
+                  'line' => 65,
+                  'node' => 'Section with other markup',
+                  'page' => 'foo|bar',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 67,
+                  'node' => '',
+                  'page' => 'chmod',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 69,
+                  'node' => '',
+                  'page' => 'chmod(2)',
+                  'type' => 'man',
+                },
+                {
+                  'line' => 71,
+                  'node' => '',
+                  'page' => 'chmod(2)',
+                  'type' => 'man',
+                },
+                {
+                  'line' => 73,
+                  'node' => '',
+                  'page' => 'chmod()',
+                  'type' => 'pod',
+                },
+                {
+                  'line' => 75,
+                  'node' => '',
+                  'page' => 'mailto:foo@cpan.org',
+                  'type' => 'url',
+                },
+                {
+                  'line' => 77,
+                  'node' => '',
+                  'page' => 'mailto:foo@cpan.org',
+                  'type' => 'url',
+                },
+                {
+                  'line' => 79,
+                  'node' => '',
+                  'page' => 'http://www.perl.org',
+                  'type' => 'url',
+                },
+                {
+                  'line' => 81,
+                  'node' => '',
+                  'page' => 'http://www.perl.org',
+                  'type' => 'url',
+                },
+            );
+
+plan 'tests' => @answers * 4 + 2;
+
+my $checker = Pod::Checker->new( '-quiet' => 1);
+$checker->parse_from_file(\*DATA);
+
+is($checker->num_warnings, 0, "There were no warnings found");
+is($checker->num_errors, 0, "There were no errors found");
+
+my @links = $checker->hyperlinks;
+
+for my $i (0 .. @links - 1) {
+    is($links[$i]->line(), $answers[$i]->{'line'}, "line() returns '$answers[$i]->{'line'}' correctly");
+    is($links[$i]->node(), $answers[$i]->{'node'}, "node() returns '$answers[$i]->{'node'}' correctly");
+    is($links[$i]->page(), $answers[$i]->{'page'}, "page() returns '$answers[$i]->{'page'}' correctly");
+    is($links[$i]->type(), $answers[$i]->{'type'}, "type() returns '$answers[$i]->{'type'}' correctly");
+}
+
+__END__
+
+=head1 NAME
+
+basic.pod - Extracted and expanded from podlators; test various link types
+
+=head1 LINKS
+
+These are all taken from the Pod::Parser tests.
+
+Try out I<LOTS> of different ways of specifying references:
+
+Reference the L<manpage/section>
+
+Reference the L<"manpage"/section>
+
+Reference the L<manpage/"section">
+
+Now try it using the new "|" stuff ...
+
+Reference the L<thistext|manpage/section>|
+
+Reference the L<thistext | manpage / section>|
+
+Reference the L<thistext| manpage/ section>|
+
+Reference the L<thistext |manpage /section>|
+
+Reference the L<thistext|manpage/"section">|
+
+Reference the L<thistext|
+manpage/
+section>|
+
+And then throw in a few new ones of my own.
+
+L<foo>
+
+L<foo|bar>
+
+L<foo/bar>
+
+L<foo/"baz boo">
+
+L</bar> won't show up because is a link to this page
+
+L</"baz boo"> won't show up because is a link to this page
+
+L</baz boo> won't show up because is a link to this page
+
+L<foo bar/baz boo>
+
+L<"boo var baz"> won't show up because the quotes make it a link to this page
+
+L<bar baz> won't show up because of blanks (deprecated) make it a link to this
+page
+
+L</boo>, L</bar>, and L</baz> won't show up because are links to this page
+
+L<fooZ<>bar>
+
+L<Testing I<italics>|foo/bar>
+
+L<foo/I<Italic> text>
+
+L<fooE<verbar>barZ<>/Section C<with> I<B<other> markup>>
+
+L<chmod>
+
+L<chmod(2)>
+
+L<man page with text|chmod(2)>
+
+L<chmod()>
+
+L<mailto:foo@cpan.org>
+
+L<Don't email us|mailto:foo@cpan.org>
+
+L<http://www.perl.org>
+
+L<hyperlink|http://www.perl.org>
+
+=head1 bar
+
+=head2 baz boo
+
+=head3 boo var baz
+
+=head4 bar baz
+
+=cut
index 03ecc5b..1c86c74 100644 (file)
@@ -14,7 +14,7 @@ exit( ($passed == 1) ? 0 : -1 )  unless $ENV{HARNESS_ACTIVE};
                                         
 ### The above line should contain spaces
 
-
+#line 18
 __END__
 
 =head2 This should cause a warning
@@ -23,6 +23,8 @@ __END__
 
 poderrors.t - test Pod::Checker on some pod syntax errors
 
+    GASP! A verbatim paragraph in NAME
+
 =unknown1 this is an unknown command with two N<unknownA>
 and D<unknownB> interior sequences.
 
@@ -46,6 +48,10 @@ sure we get a warning.
                                                
 The above blank line contains tabs and spaces only
 
+F<Many B<fcodes B<inside C<other I<fcodes F<inside I<many S<many C<more X<fcodes. S<This is X<ridiculous.>>>>>>>>>>>>
+
+A L<link|perlvar/$/> to L<perlvar/$E<sol>>
+
 =head1 Additional tests
 
 =head2 item without over
@@ -66,17 +72,17 @@ The above blank line contains tabs and spaces only
 
 =end
 
+=end something
+
 =head2 begin and begin
 
 =begin html
 
 =begin text
 
-=end
-
-=end
+=end text
 
-second one results in end w/o begin
+=end html
 
 =head2 begin w/o formatter
 
@@ -102,6 +108,7 @@ E<abcI<bla>>
 E<0x100>
 E<07777>
 E<300>
+E<unknown_entity>
 
 =head2 Unresolved internal links
 
@@ -116,10 +123,20 @@ def>
 L<>
 L<   aha>
 L<oho   >
+L<  weehee  >
 L<"Warnings"> this one is ok
 L</unescaped> ok too, this POD has an X of the same name
-L<http://www.perl.org> this is OK
-L<The Perl Home Page|http://www.perl.org> this is also OK
+
+L<<  lead >>
+L<< trail  >>
+L<< neither >>
+L<<<  both  >>>
+
+L<<<<>>>>
+
+L<<<< >>>>
+
+L<<<<  >>>>
 
 =head2 Warnings
 
@@ -134,12 +151,6 @@ L<some text with / in it|perlvar/$|> should give warnings as hell
 
 the 200 is evil
 
-=begin html
-
-What?
-
-=end xml
-
 X<unescaped>see these unescaped < and > in the text?
 
 =head2 Misc
@@ -148,12 +159,20 @@ Z<ddd> should be empty
 
 X<> should not be empty
 
+X<0> should not generate a warning about being empty
+
+E<> should not be empty
+
 =over four
 
 This paragrapgh is misplaced - it ought to be an item.
 
 =item four should be numeric!
 
+=back
+
+=over 4
+
 =item
 
 =item blah
@@ -162,10 +181,79 @@ This paragrapgh is misplaced - it ought to be an item.
 
 =back
 
-All empty over/back:
+=over
+
+    This verbatim paragraph should not be here. Spaces are on the line below this
+    
+=item *
+
+bullet
+
+=item 1
+
+number, uh oh
+
+=back
+
+=over
+
+=item *
+
+first bullet
+
+=item 1
+
+then number
+
+=item finally definition
+
+=back
+
+=over
+
+=item 1
+
+first number
+
+=item 3
+
+bad numbering
+
+=item then definition
+
+=item *
+
+finally bullet
+
+=back
+
+=over
+
+=item first defintion
+
+=item *
+
+then bullet
+
+=item 1
+
+finally number
+
+=item second definition
+
+    This should not generate an empty =item warning,
+    because it has verbatim text.
+
+=back
+
+Empty over/back:
 
 =over 4
 
+=over 2
+
+=back
+
 =back
 
 item w/o name
@@ -194,48 +282,43 @@ we already have a head Misc
 
 =head2 another one
 
-=head2 the next line should be empty
-=head2 ... but there is a command instead
+previous section is empty!
 
-And here is some text
-=head2 again followed by a command
+=head1 LINK TESTS
 
-  verbatim
-=item line missing
 
-previous section is empty!
 
-=head1 LINK TESTS
 
-Due to bug reported by Rafael Garcia-Suarez "rgarciasuarez@free.fr":
 
-The following hyperlinks :
-L<"I/O Operators">
-L<perlop/"I/O Operators">
-trigger a podchecker warning (using bleadperl) :
-    node 'I/O Operators' contains non-escaped | or /
 
-=cut
 
-=pod
 
-=head1 ON-OFF tests
 
-The above =pod is OK. The following =cut is ok, the one after not.
 
-=cut
+L<perlop/"I/O Operators">
+don't trigger a warning because node is quoted
 
-# some comment or code here, not POD
+L<"I/O Operators">
+incorrectly interpreted as 'O Operators in I', but this is deprecated syntax, as per perlpodspec.
+no warning due to quotes
 
-=cut
+=head1
 
-# more code
+Empty head above and unclosed over/begins below
 
-=head2 This opens POD
+=head3 test X<stuff> I<test>
 
-=pod
+=over
 
-And the =pod above is too much.
+=begin html
+
+What?
+
+=begin :xml
+
+L<This pod's NAME in a link means it is internal|poderrors.t/link_to_nowhere>,
+so should generate a warning
 
 =cut
 
+
index 8c16609..fe7e015 100644 (file)
@@ -1,53 +1,78 @@
 *** WARNING: =head2 without preceding higher level at line 20 in file t/pod/poderrs.t
 *** WARNING: empty section in previous paragraph at line 22 in file t/pod/poderrs.t
-*** ERROR: Unknown command 'unknown1' at line 26 in file t/pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'Q' at line 30 in file t/pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'A' at line 31 in file t/pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'Y' at line 32 in file t/pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'V' at line 32 in file t/pod/poderrs.t
-*** ERROR: unterminated B<...> at line 36 in file t/pod/poderrs.t
-*** ERROR: unterminated I<...> at line 35 in file t/pod/poderrs.t
-*** ERROR: unterminated C<...> at line 38 in file t/pod/poderrs.t
-*** WARNING: line containing nothing but whitespace in paragraph at line 46 in file t/pod/poderrs.t
-*** ERROR: =item without previous =over at line 53 in file t/pod/poderrs.t
-*** ERROR: =back without previous =over at line 57 in file t/pod/poderrs.t
-*** ERROR: =over on line 61 without closing =back (at head2) at line 65 in file t/pod/poderrs.t
-*** ERROR: =end without =begin at line 67 in file t/pod/poderrs.t
-*** ERROR: Nested =begin's (first at line 71:html) at line 73 in file t/pod/poderrs.t
-*** ERROR: =end without =begin at line 77 in file t/pod/poderrs.t
-*** ERROR: No argument for =begin at line 83 in file t/pod/poderrs.t
-*** ERROR: =for without formatter specification at line 89 in file t/pod/poderrs.t
-*** WARNING: nested commands C<...C<...>...> at line 95 in file t/pod/poderrs.t
-*** ERROR: garbled entity E<alea iacta est> at line 99 in file t/pod/poderrs.t
-*** ERROR: garbled entity E<C<auml>> at line 100 in file t/pod/poderrs.t
-*** ERROR: garbled entity E<abcI<bla>> at line 101 in file t/pod/poderrs.t
-*** ERROR: Entity number out of range E<0x100> at line 102 in file t/pod/poderrs.t
-*** ERROR: Entity number out of range E<07777> at line 103 in file t/pod/poderrs.t
-*** ERROR: Entity number out of range E<300> at line 104 in file t/pod/poderrs.t
-*** ERROR: malformed link L<> : empty link at line 116 in file t/pod/poderrs.t
-*** WARNING: ignoring leading whitespace in link at line 117 in file t/pod/poderrs.t
-*** WARNING: ignoring trailing whitespace in link at line 118 in file t/pod/poderrs.t
-*** WARNING: (section) in 'passwd(5)' deprecated at line 126 in file t/pod/poderrs.t
-*** WARNING: node '$|' contains non-escaped | or / at line 127 in file t/pod/poderrs.t
-*** WARNING: alternative text '$|' contains non-escaped | or / at line 127 in file t/pod/poderrs.t
-*** ERROR: Spurious character(s) after =back at line 133 in file t/pod/poderrs.t
-*** ERROR: Nonempty Z<> at line 147 in file t/pod/poderrs.t
-*** ERROR: Empty X<> at line 149 in file t/pod/poderrs.t
-*** WARNING: preceding non-item paragraph(s) at line 155 in file t/pod/poderrs.t
-*** WARNING: No argument for =item at line 157 in file t/pod/poderrs.t
-*** WARNING: previous =item has no contents at line 159 in file t/pod/poderrs.t
-*** WARNING: No items in =over (at line 167) / =back list at line 169 in file t/pod/poderrs.t
-*** ERROR: Spurious text after =pod at line 175 in file t/pod/poderrs.t
-*** ERROR: Spurious text after =cut at line 179 in file t/pod/poderrs.t
-*** WARNING: empty section in previous paragraph at line 195 in file t/pod/poderrs.t
-*** ERROR: Apparent command =head2 not preceded by blank line at line 198 in file t/pod/poderrs.t
-*** WARNING: empty section in previous paragraph at line 197 in file t/pod/poderrs.t
-*** ERROR: Apparent command =head2 not preceded by blank line at line 201 in file t/pod/poderrs.t
-*** ERROR: Apparent command =item not preceded by blank line at line 204 in file t/pod/poderrs.t
-*** ERROR: Spurious =cut command at line 230 in file t/pod/poderrs.t
-*** ERROR: Spurious =pod command at line 236 in file t/pod/poderrs.t
-*** ERROR: unresolved internal link 'begin or begin' at line 108 in file t/pod/poderrs.t
-*** ERROR: unresolved internal link 'end with begin' at line 109 in file t/pod/poderrs.t
-*** ERROR: unresolved internal link 'OoPs' at line 110 in file t/pod/poderrs.t
-*** ERROR: unresolved internal link 'abc def' at line 114 in file t/pod/poderrs.t
-*** ERROR: unresolved internal link 'I/O Operators' at line 213 in file t/pod/poderrs.t
+*** WARNING: Verbatim paragraph in NAME section at line 26 in file t/pod/poderrs.t
+*** ERROR: Unknown directive: =unknown1 at line 28 in file t/pod/poderrs.t
+*** ERROR: Deleting unknown formatting code Q<> at line 31 in file t/pod/poderrs.t
+*** ERROR: Deleting unknown formatting code A<> at line 31 in file t/pod/poderrs.t
+*** ERROR: Deleting unknown formatting code Y<> at line 31 in file t/pod/poderrs.t
+*** ERROR: Deleting unknown formatting code V<> at line 31 in file t/pod/poderrs.t
+*** ERROR: Unterminated I<B<...>> sequence at line 36 in file t/pod/poderrs.t
+*** ERROR: Unterminated C<...> sequence at line 40 in file t/pod/poderrs.t
+*** WARNING: line containing nothing but whitespace in paragraph at line 48 in file t/pod/poderrs.t
+*** WARNING: nested commands X<...X<...>...> at line 51 in file t/pod/poderrs.t
+*** WARNING: nested commands S<...S<...>...> at line 51 in file t/pod/poderrs.t
+*** WARNING: nested commands C<...C<...>...> at line 51 in file t/pod/poderrs.t
+*** WARNING: nested commands I<...I<...>...> at line 51 in file t/pod/poderrs.t
+*** WARNING: nested commands F<...F<...>...> at line 51 in file t/pod/poderrs.t
+*** WARNING: nested commands B<...B<...>...> at line 51 in file t/pod/poderrs.t
+*** ERROR: '=item' outside of any '=over' at line 59 in file t/pod/poderrs.t
+*** ERROR: You forgot a '=back' before '=head2' at line 61 in file t/pod/poderrs.t
+*** ERROR: =back without =over at line 63 in file t/pod/poderrs.t
+*** WARNING: empty section in previous paragraph at line 65 in file t/pod/poderrs.t
+*** ERROR: You forgot a '=back' before '=head2' at line 71 in file t/pod/poderrs.t
+*** ERROR: '=end' without a target? at line 73 in file t/pod/poderrs.t
+*** ERROR: =end something without matching =begin.  (Stack: [empty]) at line 75 in file t/pod/poderrs.t
+*** WARNING: empty section in previous paragraph at line 77 in file t/pod/poderrs.t
+*** ERROR: =begin without a target? at line 89 in file t/pod/poderrs.t
+*** ERROR: '=end' without a target? at line 91 in file t/pod/poderrs.t
+*** WARNING: empty section in previous paragraph at line 93 in file t/pod/poderrs.t
+*** ERROR: =for without a target? at line 95 in file t/pod/poderrs.t
+*** WARNING: nested commands C<...C<...>...> at line 101 in file t/pod/poderrs.t
+*** ERROR: Unknown E content in E<alea iacta est> at line 105 in file t/pod/poderrs.t
+*** ERROR: An E<...> surrounding strange content at line 105 in file t/pod/poderrs.t
+*** ERROR: An E<...> surrounding strange content at line 105 in file t/pod/poderrs.t
+*** ERROR: Unknown E content in E<unknown_entity> at line 105 in file t/pod/poderrs.t
+*** ERROR: An empty L<> at line 121 in file t/pod/poderrs.t
+*** ERROR: L<> starts or ends with whitespace at line 121 in file t/pod/poderrs.t
+*** ERROR: L<> starts or ends with whitespace at line 121 in file t/pod/poderrs.t
+*** ERROR: L<> starts or ends with whitespace at line 121 in file t/pod/poderrs.t
+*** ERROR: Unterminated L<<< ... >>> sequence at line 137 in file t/pod/poderrs.t
+*** ERROR: Unterminated L<<< ... >>> sequence at line 139 in file t/pod/poderrs.t
+*** ERROR: alternative text 'some text with / in it' contains non-escaped | or / at line 143 in file t/pod/poderrs.t
+*** ERROR: =back doesn't take any parameters, but you said =back 200 at line 150 in file t/pod/poderrs.t
+*** ERROR: A non-empty Z<> at line 158 in file t/pod/poderrs.t
+*** ERROR: An empty X<> at line 160 in file t/pod/poderrs.t
+*** ERROR: An empty E<> at line 164 in file t/pod/poderrs.t
+*** ERROR: =over should be: '=over' or '=over positive_number' at line 166 in file t/pod/poderrs.t
+*** ERROR: You can't have =items (as at line 170) unless the first thing after the =over is an =item at line 166 in file t/pod/poderrs.t
+*** WARNING: =item has no contents at line 176 in file t/pod/poderrs.t
+*** ERROR: Expected '=item *' at line 178 in file t/pod/poderrs.t
+*** ERROR: Expected '=item *' at line 180 in file t/pod/poderrs.t
+*** WARNING: line containing nothing but whitespace in paragraph at line 187 in file t/pod/poderrs.t
+*** ERROR: You can't have =items (as at line 188) unless the first thing after the =over is an =item at line 184 in file t/pod/poderrs.t
+*** ERROR: Expected '=item *' at line 204 in file t/pod/poderrs.t
+*** ERROR: Expected '=item *' at line 208 in file t/pod/poderrs.t
+*** ERROR: You have '=item 3' instead of the expected '=item 2' at line 218 in file t/pod/poderrs.t
+*** ERROR: Expected '=item 3' at line 222 in file t/pod/poderrs.t
+*** ERROR: Expected '=item 4' at line 224 in file t/pod/poderrs.t
+*** ERROR: Expected text after =item, not a bullet at line 234 in file t/pod/poderrs.t
+*** ERROR: Expected text after =item, not a number at line 238 in file t/pod/poderrs.t
+*** WARNING: empty =over/=back block at line 253 in file t/pod/poderrs.t
+*** ERROR: Spurious text after =pod at line 263 in file t/pod/poderrs.t
+*** ERROR: Spurious text after =cut at line 267 in file t/pod/poderrs.t
+*** WARNING: empty section in previous paragraph at line 283 in file t/pod/poderrs.t
+*** ERROR: empty =head1 at line 305 in file t/pod/poderrs.t
+*** ERROR: =over without closing =back at line 311 in file t/pod/poderrs.t
+*** ERROR: =begin :xml without matching =end :xml at line 317 in file t/pod/poderrs.t
+*** ERROR: =begin html without matching =end html at line 313 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'begin or begin' at line 115 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'end with begin' at line 115 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'OoPs' at line 115 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'abc def' at line 121 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link ' aha' at line 121 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'oho ' at line 121 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link ' weehee ' at line 121 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'link_to_nowhere' at line 319 in file t/pod/poderrs.t
+*** WARNING: multiple occurrences (2) of link target '*' at line - in file t/pod/poderrs.t
+*** WARNING: multiple occurrences (2) of link target '1' at line - in file t/pod/poderrs.t
+*** WARNING: multiple occurrences (2) of link target 'Misc' at line - in file t/pod/poderrs.t
index aeb0be3..8517cbd 100644 (file)
@@ -65,9 +65,10 @@ sub testpodcheck( @ ) {
          $_ = VMS::Filespec::unixify($_)  unless  ref;
       }
    }
-   podchecker($infile, $outfile);
+   podchecker($infile, $outfile, -warnings => 200);
    if ( testcmp({'-cmplines' => \&msgcmp}, $outfile, $cmpfile) ) {
        $different = "$outfile is different from $cmpfile";
+       system("diff -u $cmpfile $outfile") if $ENV{TEST_POD_CHECK_DIFF};
    }
    else {
        unlink($outfile);
index e22d4bc..322c43d 100644 (file)
@@ -331,6 +331,7 @@ pod/perlce.pod      Verbatim line length including indents exceeds 79 by    3
 pod/perldebguts.pod    Verbatim line length including indents exceeds 79 by    27
 pod/perldebtut.pod     Verbatim line length including indents exceeds 79 by    3
 pod/perldtrace.pod     Verbatim line length including indents exceeds 79 by    7
+pod/perlgit.pod        ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perlgit.pod        Verbatim line length including indents exceeds 79 by    1
 pod/perlguts.pod       ? Should you be using L<...> instead of 1
 pod/perlhack.pod       ? Should you be using L<...> instead of 1
@@ -341,6 +342,7 @@ pod/perlirix.pod    Verbatim line length including indents exceeds 79 by    1
 pod/perlmacosx.pod     Verbatim line length including indents exceeds 79 by    3
 pod/perlmodlib.pod     Verbatim line length including indents exceeds 79 by    3
 pod/perlmroapi.pod     ? Should you be using L<...> instead of 1
+pod/perlop.pod ? Should you be using F<...> or maybe L<...> instead of 2
 pod/perlos2.pod        ? Should you be using L<...> instead of 2
 pod/perlos2.pod        Verbatim line length including indents exceeds 79 by    5
 pod/perlos390.pod      Verbatim line length including indents exceeds 79 by    2
@@ -353,7 +355,8 @@ pod/perltru64.pod   Verbatim line length including indents exceeds 79 by    1
 pod/perlwin32.pod      Verbatim line length including indents exceeds 79 by    7
 porting/epigraphs.pod  Verbatim line length including indents exceeds 79 by    16
 porting/release_managers_guide.pod     Verbatim line length including indents exceeds 79 by    1
-utils/encguess There is no NAME        1
+porting/todo.pod       ? Should you be using F<...> or maybe L<...> instead of 1
+utils/ptar     Verbatim paragraph in NAME section      1
 lib/benchmark.pm       Verbatim line length including indents exceeds 79 by    2
 lib/config.pod ? Should you be using L<...> instead of -1
 lib/perl5db.pl ? Should you be using L<...> instead of 1
index cefe58f..d267f71 100644 (file)
@@ -1,5 +1,7 @@
 #!/usr/bin/perl -w
 
+package main;
+
 BEGIN {
     chdir 't';
     @INC = "../lib";
@@ -56,8 +58,7 @@ pods in the distribution workspace, except certain known special ones
 (specified below).  It does additional checking beyond that done by
 Pod::Checker, and keeps a database of known potential problems, and will
 fail a pod only if the number of such problems differs from that given in the
-database.  It also suppresses the C<(section) deprecated> message from
-Pod::Checker, since specifying the man page section number is quite proper to do.
+database.
 
 The additional checks it always makes are:
 
@@ -92,13 +93,6 @@ missing from the C<LE<lt>E<gt>> pod command.
 A pod can't be linked to unless it has a unique name.
 And a NAME should have a dash and short description after it.
 
-=item =encoding statement issues
-
-This indicates if an C<=encoding> statement should be present, or moved to the
-front of the pod.
-
-=back
-
 If the C<PERL_POD_PEDANTIC> environment variable is set or the C<--pedantic>
 command line argument is provided then a few more checks are made.
 The pedantic checks are:
@@ -161,6 +155,8 @@ Another problem is that there is currently no check that modules listed as
 valid in the database
 actually are.  Thus any errors introduced there will remain there.
 
+=back
+
 =head2 Specially handled pods
 
 =over
@@ -363,8 +359,6 @@ my $broken_link = "Apparent broken link";
 my $broken_internal_link = "Apparent internal link is missing its forward slash";
 my $multiple_targets = "There is more than one target";
 my $duplicate_name = "Pod NAME already used";
-my $need_encoding = "Should have =encoding statement because have non-ASCII";
-my $encoding_first = "=encoding must be first command (if present)";
 my $no_name = "There is no NAME";
 my $missing_name_description = "The NAME should have a dash and short description after it";
 # the pedantic warnings messages
@@ -385,9 +379,6 @@ my $dl_ext  = $Config{'dlext'};   $dl_ext  =~ tr/.//d;
 my %excluded_files = (
                         canonicalize("lib/unicore/mktables") => 1,
                         canonicalize("Porting/make-rmg-checklist") => 1,
-                        # this one is a POD, but unfinished, so skip
-                        # it for now
-                        canonicalize("Porting/perl5200delta.pod") => 1,
                         canonicalize("Porting/perldelta_template.pod") => 1,
                         canonicalize("regen/feature.pl") => 1,
                         canonicalize("regen/warnings.pl") => 1,
@@ -440,19 +431,26 @@ my $non_pods = qr/ (?: \.
                 /x;
 
 # Matches something that looks like a file name, but is enclosed in C<...>
-my $C_path_re = qr{ \b ( C<
+my $C_path_re = qr{ ^
                         # exclude various things that have slashes
                         # in them but aren't paths
                         (?!
                             (?: (?: s | qr | m) / ) # regexes
-                            | \d+/\d+>       # probable fractions
-                            | OS/2>
-                            | Perl/Tk>
-                            | origin/blead>
-                            | origin/maint
-                            | -    # File names don't begin with "-"
-                            )
-                            [-\w]+ (?: / [-\w]+ )+ (?: \. \w+ )? > )
+                            | \d+/\d+ \b       # probable fractions
+                            | (?: [LF] < )+
+                            | OS/2 \b
+                            | Perl/Tk \b
+                            | origin/blead \b
+                            | origin/maint \b
+
+                        )
+                        /?  # Optional initial slash
+                        \w+ # First component of path, doesn't begin with
+                            # a minus
+                        (?: / [-\w]+ )+ # Subsequent path components
+                        (?: \. \w+ )?   # Optional trailing dot and suffix
+                        >*  # Any enclosed L< F< have matching closing >
+                        $
                     }x;
 
 # '.PL' files should be excluded, as they aren't final pods, but often contain
@@ -480,20 +478,19 @@ close $manifest_fh, or die "Can't close $MANIFEST";
 
 # Pod::Checker messages to suppress
 my @suppressed_messages = (
-    "(section) in",                         # Checker is wrong to flag this
-    "multiple occurrence of link target",   # We catch independently the ones
-                                            # that are real problems.
-    "unescaped <>",
-    "Entity number out of range",   # Checker outputs this for anything above
-                                    # 255, but in fact all Unicode is valid
-    "No items in =over",            # ie a blockquote
+    # We catch independently the ones that are real problems.
+    qr/multiple occurrences \(\d+\) of link target/,
+
+    "unescaped <>",                 # Not every '<' or '>' need be escaped
+    qr/No items in =over/,          # i.e., a blockquote, which we consider legal
 );
 
 sub suppressed {
     # Returns bool as to if input message is one that is to be suppressed
 
     my $message = shift;
-    return grep { $message =~ /^\Q$_/i } @suppressed_messages;
+
+    return grep { $message =~ /^$_/i } @suppressed_messages;
 }
 
 {   # Closure to contain a simple subset of test.pl.  This is to get rid of the
@@ -643,37 +640,54 @@ package My::Pod::Checker {      # Extend Pod::Checker
 
     # Uses inside out hash to protect from typos
     # For new fields, remember to add to destructor DESTROY()
-    my %indents;            # Stack of indents from =over's in effect for
-                            # current line
+    my %CFL_text;           # The text comprising the current C<>, F<>, or L<>
+    my %C_text;             # If defined, are in a C<> section, and includes
+                            # the accumulated text from that
     my %current_indent;     # Current line's indent
     my %filename;           # The pod is store in this file
-    my %skip;               # is SKIP set for this pod
+    my %in_CFL;             # count of stacked C<>, F<>, L<> directives
+    my %indents;            # Stack of indents from =over's in effect for
+                            # current line
+    my %in_for;             # true if in a =for or =begin
     my %in_NAME;            # true if within NAME section
     my %in_begin;           # true if within =begin section
+    my %in_X;               # true if in a X<>
     my %linkable_item;      # Bool: if the latest =item is linkable.  It isn't
                             # for bullet and number lists
     my %linkable_nodes;     # Pod::Checker adds all =items to its node list,
                             # but not all =items are linkable to
-    my %seen_encoding_cmd;  # true if have =encoding earlier
+    my %running_CFL_text;   # The current text that is being accumulated until
+                            # an end_FOO is found, and this includes any C<>,
+                            # F<>, or L<> directives.
+    my %running_simple_text; # The currentt text that is being accumulated
+                            # until an end_FOO is found, and all directives
+                            # have been expanded into plain text
     my %command_count;      # Number of commands seen
     my %seen_pod_cmd;       # true if have =pod earlier
-    my %warned_encoding;    # true if already have warned about =encoding
-                            # problems
+    my %skip;               # is SKIP set for this pod
+    my %start_line;         # the first input line number in the the thing
+                            # currently being worked on
 
     sub DESTROY {
         my $addr = Scalar::Util::refaddr $_[0];
+        delete $CFL_text{$addr};
+        delete $C_text{$addr};
         delete $command_count{$addr};
         delete $current_indent{$addr};
         delete $filename{$addr};
         delete $in_begin{$addr};
+        delete $in_CFL{$addr};
         delete $indents{$addr};
+        delete $in_for{$addr};
         delete $in_NAME{$addr};
+        delete $in_X{$addr};
         delete $linkable_item{$addr};
         delete $linkable_nodes{$addr};
-        delete $seen_encoding_cmd{$addr};
+        delete $running_CFL_text{$addr};
+        delete $running_simple_text{$addr};
         delete $seen_pod_cmd{$addr};
         delete $skip{$addr};
-        delete $warned_encoding{$addr};
+        delete $start_line{$addr};
         return;
     }
 
@@ -688,11 +702,11 @@ package My::Pod::Checker {      # Extend Pod::Checker
         $current_indent{$addr} = 0;
         $filename{$addr} = $filename;
         $in_begin{$addr} = 0;
+        $in_X{$addr} = 0;
+        $in_CFL{$addr} = 0;
         $in_NAME{$addr} = 0;
         $linkable_item{$addr} = 0;
-        $seen_encoding_cmd{$addr} = 0;
         $seen_pod_cmd{$addr} = 0;
-        $warned_encoding{$addr} = 0;
         return $self;
     }
 
@@ -794,88 +808,163 @@ package My::Pod::Checker {      # Extend Pod::Checker
         #push @{$problems{$self->get_filename}{$message}}, $opts;
     }
 
-    sub check_encoding {    # Does it need an =encoding statement?
-        my ($self, $paragraph, $line_num, $pod_para) = @_;
+    # In the next subroutines, we keep track of the text of the current
+    # innermost thing, like F<fooC<bar>baz>.  The things we care about raising
+    # messages about in this program all come from a single sequence of
+    # characters uninterrupted by other pod commands.  Therefore we don't have
+    # to worry about recursion, and we can just set the string we care about
+    # to empty on entrance to each command.
+
+    sub handle_text {
+        # This is called by the parent class to deal with any straight text.
+        # We mostly just append this to the running current value which will
+        # be dealt with upon the end of the current construct, like a
+        # paragraph.  But certain things don't contribute to checking the pod
+        # and are ignored.  We also have set flags to indicate this text is
+        # going towards constructing certain constructs, and handle those
+        # specially.
 
-        # Do nothing if there is an =encoding in the file, or if the line
-        # doesn't require an =encoding, or have already warned.
+        my $self = shift;
         my $addr = Scalar::Util::refaddr $self;
-        return if $seen_encoding_cmd{$addr}
-                    || $warned_encoding{$addr}
-                    || $paragraph !~ /\P{ASCII}/;
-
-        $warned_encoding{$addr} = 1;
-        my ($file, $line) = $pod_para->file_line;
-        $self->poderror({ -line => $line, -file => $file,
-                          -msg => $need_encoding
-                        });
-        return;
+
+        my $return = $self->SUPER::handle_text(@_);
+
+        if ($in_X{$addr} || $in_for{$addr}) { # ignore
+            return $return;
+        }
+
+        my $text = join "\n", @_;
+        $running_simple_text{$addr} .= $text;
+
+        # Keep separate tabs on C<>, F<>, and L<> directives, and one
+        # especially for C<> ones.
+        if ($in_CFL{$addr}) {
+            $CFL_text{$addr} .= $text;
+            $C_text{$addr} .= $text if defined $C_text{$addr};
+        }
+        else {
+            # This variable is updated instead in the corresponding C, F, or L
+            # handler.
+            $running_CFL_text{$addr} .= $text;
+        }
+
+        return $return;
     }
 
-    sub verbatim {
-        my ($self, $paragraph, $line_num, $pod_para) = @_;
-        $self->check_encoding($paragraph, $line_num, $pod_para);
+    # The start_FOO routines check that somehow a C<> construct hasn't escaped
+    # without being checked, and initialize things, and call the parent
+    # class's equivalent routine.
+
+    # The end_FOO routines close things off, and check the text that has been
+    # accumulated for FOO, then call the parent's corresponding routine.
 
-        $self->SUPER::verbatim($paragraph, $line_num, $pod_para);
+    sub start_Para {
+        my $self = shift;
+        check_see_but_not_link($self);
 
         my $addr = Scalar::Util::refaddr $self;
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+        return $self->SUPER::start_Para(@_);
+    }
 
-        # Pick up the name, since the parent class doesn't in verbatim
-        # NAMEs; so treat as non-verbatim.  The parent class only allows one
-        # paragraph in a NAME section, so if there is an extra blank line, it
-        # will trigger a message, but such a blank line is harmless, so skip
-        # in that case.
-        if ($in_NAME{$addr} && $paragraph =~ /\S/) {
-            $self->textblock($paragraph, $line_num, $pod_para);
-        }
+    sub start_item_text {
+        my $self = shift;
+        check_see_but_not_link($self);
 
-        my @lines = split /^/, $paragraph;
-        for my $i (0 .. @lines - 1) {
-            if ( my $encoding = $seen_encoding_cmd{$addr} ) {
-              require Encode;
-              $lines[$i] = Encode::decode($encoding, $lines[$i]);
-            }
-            $lines[$i] =~ s/\s+$//;
-            my $indent = $self->get_current_indent;
-
-            if ($pedantic) { # TODO: this check should be moved higher
-                                 # to avoid more unnecessary work
-                my $exceeds = length(Text::Tabs::expand($lines[$i]))
-                    + $indent - $MAX_LINE_LENGTH;
-                next unless $exceeds > 0;
-                my ($file, $line) = $pod_para->file_line;
-                $self->poderror({ -line => $line + $i, -file => $file,
-                    -msg => $line_length,
-                    parameter => "+$exceeds (including " . ($indent - $INDENT) . " from =over's)",
-                });
-            }
-        }
+        my $addr = Scalar::Util::refaddr $self;
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+
+        # This is the only =item that is linkable
+        $linkable_item{$addr} = 1;
+
+        return $self->SUPER::start_item_text(@_);
     }
 
-    sub textblock {
-        my ($self, $paragraph, $line_num, $pod_para) = @_;
-        $self->check_encoding($paragraph, $line_num, $pod_para);
+    sub start_item_number {
+        my $self = shift;
+        check_see_but_not_link($self);
 
-        $self->SUPER::textblock($paragraph, $line_num, $pod_para);
+        my $addr = Scalar::Util::refaddr $self;
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+
+        return $self->SUPER::start_item_number(@_);
+    }
+
+    sub start_item_bullet {
+        my $self = shift;
+        check_see_but_not_link($self);
 
-        my ($file, $line) = $pod_para->file_line;
         my $addr = Scalar::Util::refaddr $self;
-        if ($in_NAME{$addr}) {
-            if (! $self->name) {
-                my $text = $self->interpolate($paragraph, $line_num);
-                if ($text =~ /^\s*(\S+?)\s*$/) {
-                    $self->name($1);
-                    $self->poderror({ -line => $line, -file => $file,
-                        -msg => $missing_name_description,
-                        parameter => $1});
-                }
-            }
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+
+        return $self->SUPER::start_item_bullet(@_);
+    }
+
+    sub end_item {  # No difference in =item types endings
+        my $self = shift;
+        check_see_but_not_link($self);
+        return $self->SUPER::end_item(@_);
+    }
+
+    sub start_over {
+        my $self = shift;
+        check_see_but_not_link($self);
+
+        my $addr = Scalar::Util::refaddr $self;
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+
+        # Save this indent on a stack, and keep track of total indent
+        my $indent =  $_[0]{'indent'};
+        push @{$indents{$addr}}, $indent;
+        $current_indent{$addr} += $indent;
+
+        return $self->SUPER::start_over(@_);
+    }
+
+    sub end_over_bullet { shift->end_over(@_) }
+    sub end_over_number { shift->end_over(@_) }
+    sub end_over_text   { shift->end_over(@_) }
+    sub end_over_block  { shift->end_over(@_) }
+    sub end_over_empty  { shift->end_over(@_) }
+    sub end_over {
+        my $self = shift;
+        check_see_but_not_link($self);
+
+        my $addr = Scalar::Util::refaddr $self;
+
+        # Pop current indent
+        if (@{$indents{$addr}}) {
+            $current_indent{$addr} -= pop @{$indents{$addr}};
         }
-        $paragraph = join " ", split /^/, $paragraph;
+        else {
+            # =back without corresponding =over, but should have
+            # warned already
+            $current_indent{$addr} = 0;
+        }
+    }
+
+    sub check_see_but_not_link {
 
-        # If looks like a reference to other documentation by containing the
-        # word 'See' and then a likely pod directive, warn.
-        while ($paragraph =~ m{
+        # Looks through accumulated text for current element that includes the
+        # C<>, F<>, and L<> directives for ones that look like they are
+        # C<link> instead of L<link>.
+
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        return unless defined $running_CFL_text{$addr};
+
+        while ($running_CFL_text{$addr} =~ m{
                                 ( (?: \w+ \s+ )* )  # The phrase before, if any
                                 \b [Ss]ee \s+
                                 ( ( [^L] )
@@ -884,7 +973,8 @@ package My::Pod::Checker {      # Extend Pod::Checker
                                   >
                                 )
                                 ( \s+ (?: under | in ) \s+ L< )?
-                            }xg) {
+                            }xg)
+        {
             my $prefix = $1 // "";
             my $construct = $2;     # The whole thing, like C<...>
             my $type = $3;
@@ -901,25 +991,13 @@ package My::Pod::Checker {      # Extend Pod::Checker
                 # 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
+                    && $interior !~ / \s /x
 
                     # F<> that end in eg \.pl are almost certainly ok, as are
                     # those that look like a path with multiple "/" chars
@@ -930,139 +1008,266 @@ package My::Pod::Checker {      # Extend Pod::Checker
                     )
                 ) {
                     # TODO: move the checking of $pedantic higher up
-                    $self->poderror({ -line => $line, -file => $file,
+                    $self->poderror({ -line => $start_line{$addr},
                         -msg => $C_not_linked,
                         parameter => $construct
-                    }) if $pedantic;
+                    });
                 }
             }
         }
-        while ($paragraph =~ m/$C_path_re/g) {
-            my $construct = $1;
-            # TODO: move the checking of $pedantic higher up
-            $self->poderror({ -line => $line, -file => $file,
-                -msg => $C_with_slash,
-                parameter => $construct
-            }) if $pedantic;
-        }
-        return;
+
+        undef $running_CFL_text{$addr};
     }
 
-    sub command {
-        my ($self, $cmd, $paragraph, $line_num, $pod_para) = @_;
+    sub end_Para {
+        my $self = shift;
+        check_see_but_not_link($self);
+
         my $addr = Scalar::Util::refaddr $self;
-        if ($cmd eq "pod") {
-            $seen_pod_cmd{$addr}++;
-        }
-        elsif ($cmd eq "encoding") {
-            my ($file, $line) = $pod_para->file_line;
-            $seen_encoding_cmd{$addr} = $paragraph; # for later decoding
-            if ($command_count{$addr} != 1 && $seen_pod_cmd{$addr}) {
-                $self->poderror({ -line => $line, -file => $file,
-                                  -msg => $encoding_first
-                                });
+        if ($in_NAME{$addr}) {
+            if ($running_simple_text{$addr} =~ /^\s*(\S+?)\s*$/) {
+                $self->poderror({ -line => $start_line{$addr},
+                    -msg => $missing_name_description,
+                    parameter => $1});
             }
+            $in_NAME{$addr} = 0;
         }
-        $self->check_encoding($paragraph, $line_num, $pod_para);
-
-        # Pod::Check treats all =items as linkable, but the bullet and
-        # numbered lists really aren't.  So keep our own list.  This has to be
-        # processed before SUPER is called so that the list is started before
-        # the rest of it gets parsed.
-        if ($cmd eq 'item') { # Not linkable if item begins with * or a digit
-            $linkable_item{$addr} = ($paragraph !~ / ^ \s*
-                                                   (?: [*]
-                                                   | \d+ \.? (?: \$ | \s+ )
-                                                   )/x)
-                                  ? 1
-                                  : 0;
+        $self->SUPER::end_Para(@_);
+    }
+
+    sub start_head1 {
+        my $self = shift;
+        check_see_but_not_link($self);
 
+        my $addr = Scalar::Util::refaddr $self;
+        $start_line{$addr} = $_[0]->{start_line};
+        $running_CFL_text{$addr} = "";
+        $running_simple_text{$addr} = "";
+
+        return $self->SUPER::start_head1(@_);
+    }
+
+    sub end_head1 {  # This is called at the end of the =head line.
+        my $self = shift;
+        check_see_but_not_link($self);
+
+        my $addr = Scalar::Util::refaddr $self;
+
+        $in_NAME{$addr} = 1 if $running_simple_text{$addr} eq 'NAME';
+        return $self->SUPER::end_head(@_);
+    }
+
+    sub start_Verbatim {
+        my $self = shift;
+        check_see_but_not_link($self);
+
+        my $addr = Scalar::Util::refaddr $self;
+        $running_simple_text{$addr} = "";
+        $start_line{$addr} = $_[0]->{start_line};
+        return $self->SUPER::start_Verbatim(@_);
+    }
+
+    sub end_Verbatim {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        # Pick up the name if it looks like one, since the parent class
+        # doesn't handle verbatim NAMEs
+        if ($in_NAME{$addr}
+            && $running_simple_text{$addr} =~ /^\s*(\S+?)\s*[,-]/)
+        {
+            $self->name($1);
         }
-        $self->SUPER::command($cmd, $paragraph, $line_num, $pod_para);
-
-        $command_count{$addr}++;
-
-        $in_NAME{$addr} = 0;    # Will change to 1 below if necessary
-        $in_begin{$addr} = 0;   # ibid
-        if ($cmd eq 'over') {
-            my $text = $self->interpolate($paragraph, $line_num);
-            my $indent = 4; # default
-            $indent = $1 if $text && $text =~ /^\s*(\d+)\s*$/;
-            push @{$indents{$addr}}, $indent;
-            $current_indent{$addr} += $indent;
+
+        my $indent = $self->get_current_indent;
+
+        # Look at each line to verify it is short enough
+        my @lines = split /^/, $running_simple_text{$addr};
+        for my $i (0 .. @lines - 1) {
+            $lines[$i] =~ s/\s+$//;
+            my $exceeds = length(Text::Tabs::expand($lines[$i]))
+                        + $indent - $MAX_LINE_LENGTH;
+            next unless $exceeds > 0;
+
+            $self->poderror({ -line => $start_line{$addr} + $i,
+                -msg => $line_length,
+                parameter => "+$exceeds (including " . ($indent - $INDENT) . " from =over's)",
+            });
         }
-        elsif ($cmd eq 'back') {
-            if (@{$indents{$addr}}) {
-                $current_indent{$addr} -= pop @{$indents{$addr}};
+
+        undef $running_simple_text{$addr};
+
+        # Parent class didn't bother to define this
+        #return $self->SUPER::SUPER::end_Verbatim(@_);
+    }
+
+    sub start_C {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $C_text{$addr} = "";
+
+        # If not in a stacked set of C<>, F<> and L<>, initialize the text for
+        # them.
+        $CFL_text{$addr} = "" if ! $in_CFL{$addr};
+        $in_CFL{$addr}++;
+
+        return $self->SUPER::start_C(@_);
+    }
+
+    sub start_F {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $CFL_text{$addr} = "" if ! $in_CFL{$addr};
+        $in_CFL{$addr}++;
+        return $self->SUPER::start_F(@_);
+    }
+
+    sub start_L {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $CFL_text{$addr} = "" if ! $in_CFL{$addr};
+        $in_CFL{$addr}++;
+        return $self->SUPER::start_L(@_);
+    }
+
+    sub end_C {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        # Warn if looks like a file or link enclosed instead by this C<>
+        if ($C_text{$addr} =~ qr/^ $C_path_re $/x) {
+            # Here it does look like it could be be a file path or a link.
+            # But some varieties of regex patterns could also fit with what we
+            # have so far.  Weed those out as best we can.  '/foo/' is almost
+            # certainly meant to be a pattern, as is '/foo/g'.
+            my $is_pattern;
+            if ($C_text{$addr} !~ qr| ^ / [^/]* / ( [msixpodualngcr]* ) $ |x) {
+                $is_pattern = 0;
             }
             else {
-                 # =back without corresponding =over, but should have
-                 # warned already
-                $current_indent{$addr} = 0;
-            }
-        }
-        elsif ($cmd =~ /^head/) {
-            if (! $in_begin{$addr}) {
 
-                # If a particular formatter, then this command doesn't really
-                # apply
-                $current_indent{$addr} = 0;
-                undef @{$indents{$addr}};
+                # Here, it looks like a pattern potentially followed by some
+                # modifiers.  To make doubly sure, don't count as patterns
+                # those constructs which have more occurrences (generally 1)
+                # of a modifier than is legal.
+                my %counts;
+                map { $counts{$_}++ } split "", $1;
+                foreach my $modifier (keys %counts) {
+                    if ($counts{$modifier} > (($modifier eq 'a')
+                                              ? 2
+                                              : 1))
+                    {
+                        $is_pattern = 0;
+                        last;
+                    }
+                }
+                $is_pattern = 1 unless defined $is_pattern;
             }
 
-            my $text = $self->interpolate($paragraph, $line_num);
-            $in_NAME{$addr} = 1 if $cmd eq 'head1'
-                                   && $text && $text =~ /^NAME\b/;
-        }
-        elsif ($cmd eq 'begin') {
-            $in_begin{$addr} = 1;
+            unless ($is_pattern) {
+                $self->poderror({ -line => $start_line{$addr},
+                    -msg => $C_with_slash,
+                    parameter => "C<$C_text{$addr}>"
+                });
+            }
         }
+        undef $C_text{$addr};
+
+        # Add the current text to the running total.  This was not done in
+        # handle_text(), because it just sees the plain text of the innermost
+        # stacked directive.  We want to keep all the directive names
+        # enclosing the text.  Otherwise the fact that C<L<foobar>> is to a
+        # link would be lost, as the L<> would be gone.
+        $CFL_text{$addr} = "C<$CFL_text{$addr}>";
+
+        # Add this text to the the whole running total only if popping this
+        # directive off the stack leaves it empty.  As long as something is on
+        # the stack, it gets added to $CFL_text (just above).  It is only
+        # entirely constructed when the stack is empty.
+        $in_CFL{$addr}--;
+        $running_CFL_text{$addr} .= $CFL_text{$addr} if ! $in_CFL{$addr};
+
+        return $self->SUPER::end_C(@_);
+    }
 
-        return;
+    sub end_F {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $CFL_text{$addr} = "F<$CFL_text{$addr}>";
+        $in_CFL{$addr}--;
+        $running_CFL_text{$addr} .= $CFL_text{$addr} if ! $in_CFL{$addr};
+        return $self->SUPER::end_F(@_);
     }
 
-    sub hyperlink {
+    sub end_L {
         my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
 
-        my $page;
-        if ($_[0] && ($page = $_[0][1]{'-page'})) {
-            my $node = $_[0][1]{'-node'};
-
-            if ($node) {
-                $_[0][1]{'-node'} = $node = do {
-                    my $expand_seq = sub {
-                        my (undef, $seq) = @_;
-                        my $arg = join '', $seq->parse_tree->children;
-                        if ($seq->name eq 'E') {
-                            $arg =
-                                $arg eq 'sol'    ? '/' :
-                                $arg eq 'verbar' ? '|' :
-                                $arg eq 'lt'     ? '<' :
-                                $arg eq 'gt'     ? '>' :
-                                die "Not implemented: E<$arg>";
-                        }
-                        return $arg;
-                    };
-                    my $ptree = $self->parse_text({ -expand_seq => $expand_seq }, $node, $_[0][0]);
-                    join '', $ptree->children
-                };
-
-                # If the hyperlink is to an interior node of another page, save it
-                # so that we can see if we need to parse normally skipped files.
-                $has_referred_to_node{$page} = 1;
-            }
+        $CFL_text{$addr} = "L<$CFL_text{$addr}>";
+        $in_CFL{$addr}--;
+        $running_CFL_text{$addr} .= $CFL_text{$addr} if ! $in_CFL{$addr};
+        return $self->SUPER::end_L(@_);
+    }
+
+    sub start_X {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $in_X{$addr} = 1;
+        return $self->SUPER::start_X(@_);
+    }
+
+    sub end_X {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $in_X{$addr} = 0;
+        return $self->SUPER::end_X(@_);
+    }
+
+    sub start_for {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $in_for{$addr} = 1;
+        return $self->SUPER::start_for(@_);
+    }
+
+    sub end_for {
+        my $self = shift;
+        my $addr = Scalar::Util::refaddr $self;
+
+        $in_for{$addr} = 0;
+        return $self->SUPER::end_for(@_);
+    }
+
+    sub hyperlink {
+        my ($self, $link) = @_;
+
+        if ($link && $link->type eq 'pod') {
+            my $page = $link->page;
+            my $node = $link->node;
+
+            # If the hyperlink is to an interior node of another page, save it
+            # so that we can see if we need to parse normally skipped files.
+            $has_referred_to_node{$page} = 1 if $node;
 
             # Ignore certain placeholder links in perldelta.  Check if the
             # link is page-level, and also check if to a node within the page
-            if ($self->name && $self->name eq "perldelta"
-                && ((grep { $page eq $_ } @perldelta_ignore_links)
-                    || ($node
+            if (   $self->name && $self->name eq "perldelta"
+                && ((  grep { $page eq $_ } @perldelta_ignore_links)
+                    || (   $node
                         && (grep { "$page/$node" eq $_ } @perldelta_ignore_links)
             ))) {
                 return;
             }
         }
-        return $self->SUPER::hyperlink($_[0]);
+
+        return $self->SUPER::hyperlink($link);
     }
 
     sub node {
@@ -1116,7 +1321,7 @@ package My::Pod::Checker {      # Extend Pod::Checker
         # ignores 2nd param, which is output file.  Always uses undef
 
         if (open my $in_fh, '<:bytes', $filename) {
-            $self->SUPER::parse_from_filehandle($in_fh, undef);
+            $self->SUPER::parse_from_file($in_fh, undef);
             close $in_fh;
             return 1;
         }
@@ -1322,6 +1527,7 @@ sub my_safer_print {    # print, with error checking for outputting to db
 sub extract_pod {   # Extracts just the pod from a file; returns undef if file
                     # doesn't exist
     my $filename = shift;
+    use Pod::Parser;
 
     my @pod;
 
@@ -1763,21 +1969,24 @@ foreach my $filename (@files) {
 if (! $has_input_files) {
     foreach my $filename (@files) {
         next if $filename_to_checker{$filename}->get_skip;
+
         my $checker = $filename_to_checker{$filename};
-        foreach my $link ($checker->hyperlink) {
-            my $linked_to_page = $link->[1]->page;
+        foreach my $link ($checker->hyperlinks()) {
+            my $linked_to_page = $link->page;
             next unless $linked_to_page;   # intra-file checks are handled by std
                                            # Pod::Checker
+            # Currently, we assume all external links are valid
+            next if $link->type eq 'url';
 
             # Initialize the potential message.
             my %problem = ( -msg => $broken_link,
-                            -line => $link->[0],
+                            -line => $link->line,
                             parameter => "to \"$linked_to_page\"",
                         );
 
             # See if we have found the linked-to_file in our parse
             if (exists $nodes{$linked_to_page}) {
-                my $node = $link->[1]->node;
+                my $node = $link->node;
 
                 # If link is only to the page-level, already have it
                 next if ! $node;
@@ -1801,7 +2010,7 @@ if (! $has_input_files) {
                 }
 
             } # Linked-to-file not in parse; maybe is in exception list
-            elsif (! exists $valid_modules{$link->[1]->page}) {
+            elsif (! exists $valid_modules{$link->page}) {
 
                 # Here, is a link to a target that we can't find.  Check if
                 # there is an internal link on the page with the target name.
@@ -2008,3 +2217,5 @@ if ($regen) {
     chdir $original_dir || die "Can't change directories to $original_dir";
     close_and_rename($copy_fh);
 }
+
+1;