On Tue Dec 08 14:08:14 2009, GLEACH wrote:
Show quoted text> With '=begin stopwords ... =end stopwords' at the _beginning_ of the
> (.pl) file, Pod::Parser does not see any of the remaining POD. Works OK
> with the stopwords at the _end_ of the POD, but the perlcritic can't
> find them. (sigh)
Perlcritic makes a compelling case that it's not their problem -- see
#52570. I've attached a testcase. Just execute it.
#!/usr/bin/perl
use Pod::Usage;
pod2usage( -verbose => 2 );
exit 0;
__END__
=pod
=begin stopwords
notfound
notwanted
builtin
nobare
itemopt
=end stopwords
=head1 SYNOPSIS
Shows the use of C<Getopt::Auto>.
./tour.pl <options>
=head1 DESCRIPTION
Some things to try.
The options listed below. Pretty obvious.
C<tour.pl> without any options. Notice how we check for that.
Notice C<use Getopt::Auto> has a hashref as argument. The C<okerror> allows
some additional processing after command-line errors (such as "not a registered option")
are detected.
C<tour.pl -food>: Notice how it's split up.
C<tour.pl --notexpected notfound - notwanted>. Notice that --notexpected (double dash) is left on the
command line, whereas -notexpected (single dash) would not be. "notfound" is something that might have been
processed by --notexpected, had it been expected. "notwanted" would not be processed in
any case because it follows the "Cease and Desist" marker, "-".
C<tour.pl --itemopt 12 --itemopt xy> demonstrates multiple uses of a single option (not very
exciting) and how an option can process its values. Complexity limited only by your
imagination (and tolerance for user errors!)
C<tour.pl --item work>, just to prove that the documentation does not lie.
C<tour.pl --nodef>. What a surprise! Where's the =head2?
=head1 OPTIONS
Ok, here we go.
=head2 -u, --usage - Prints the DESCRIPTION.
=head2 -h, --help - Overrides the builtin.
=head2 -c, --cutup - The c option
=head2 -f - The f option, part of the -food demo
Cutup (and c) do not have subs, so to see that they are called, we must
check %options.
As we're going to all this trouble to create POD, it seems a shame not
to use it. Note that help() is not called in the code. It happens before
anything else.
=head2 work - do the work!
This would be a bare option, except that we've said 'nobare'
in the configuration
to outlaw bareness. This is not a nude beach, after all.
=head2 --item options
Note that there is no ' - ', so not an option
What follows is an option that is introduced by "=item".
=over 4
=item --itemopt - Which is an option in an item
Note that there is no '-i'
This option has an integer argument.
=back
=cut
