Login
Convert L<Some::Module> escapes to
authorElliot Shank <perl@galumph.com>
Mon, 7 Jul 2008 16:09:13 +0000 (16:09 +0000)
committerElliot Shank <perl@galumph.com>
Mon, 7 Jul 2008 16:09:13 +0000 (16:09 +0000)
L<Some::Module|Some::Module> in response to RT #37485.

175 files changed:
TODO.pod
bin/perlcritic
doc/PolicyParameter_Notes.pod
examples/generatestats
examples/loadanalysisdb
inc/Perl/Critic/BuildUtilities.pm
lib/Perl/Critic.pm
lib/Perl/Critic/Config.pm
lib/Perl/Critic/DEVELOPER.pod
lib/Perl/Critic/Document.pm
lib/Perl/Critic/Exception.pm
lib/Perl/Critic/Exception/AggregateConfiguration.pm
lib/Perl/Critic/Exception/Configuration.pm
lib/Perl/Critic/Exception/Configuration/Generic.pm
lib/Perl/Critic/Exception/Configuration/Option.pm
lib/Perl/Critic/Exception/Configuration/Option/Global.pm
lib/Perl/Critic/Exception/Configuration/Option/Global/ExtraParameter.pm
lib/Perl/Critic/Exception/Configuration/Option/Policy.pm
lib/Perl/Critic/Exception/Configuration/Option/Policy/ExtraParameter.pm
lib/Perl/Critic/Exception/Configuration/Option/Policy/ParameterValue.pm
lib/Perl/Critic/Exception/Fatal.pm
lib/Perl/Critic/Exception/Fatal/Internal.pm
lib/Perl/Critic/OptionsProcessor.pm
lib/Perl/Critic/Policy.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitBooleanGrep.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitComplexMappings.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitLvalueSubstr.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitReverseSortBlock.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitSleepViaSelect.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringyEval.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringySplit.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitUniversalCan.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitUniversalIsa.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitVoidGrep.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitVoidMap.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockGrep.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockMap.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireGlobFunction.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireSimpleSortBlock.pm
lib/Perl/Critic/Policy/ClassHierarchies/ProhibitAutoloading.pm
lib/Perl/Critic/Policy/ClassHierarchies/ProhibitExplicitISA.pm
lib/Perl/Critic/Policy/ClassHierarchies/ProhibitOneArgBless.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitHardTabs.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitParensWithBuiltins.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitQuotedWordLists.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitTrailingWhitespace.pm
lib/Perl/Critic/Policy/CodeLayout/RequireConsistentNewlines.pm
lib/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm
lib/Perl/Critic/Policy/CodeLayout/RequireTrailingCommas.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitCStyleForLoops.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitCascadingIfElse.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitDeepNests.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitLabelsWithSpecialBlockNames.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitMutatingListFunctions.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitNegativeExpressionsInUnlessAndUntilConditions.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitPostfixControls.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitUnlessBlocks.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitUnreachableCode.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitUntilBlocks.pm
lib/Perl/Critic/Policy/Documentation/PodSpelling.pm
lib/Perl/Critic/Policy/Documentation/RequirePackageMatchesPodName.pm
lib/Perl/Critic/Policy/Documentation/RequirePodAtEnd.pm
lib/Perl/Critic/Policy/Documentation/RequirePodSections.pm
lib/Perl/Critic/Policy/ErrorHandling/RequireCarping.pm
lib/Perl/Critic/Policy/ErrorHandling/RequireCheckingReturnValueOfEval.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitBacktickOperators.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitBarewordFileHandles.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitExplicitStdin.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitInteractiveTest.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitJoinedReadline.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitOneArgSelect.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitReadlineInForLoop.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitTwoArgOpen.pm
lib/Perl/Critic/Policy/InputOutput/RequireBracedFileHandleWithPrint.pm
lib/Perl/Critic/Policy/InputOutput/RequireBriefOpen.pm
lib/Perl/Critic/Policy/InputOutput/RequireCheckedClose.pm
lib/Perl/Critic/Policy/InputOutput/RequireCheckedOpen.pm
lib/Perl/Critic/Policy/InputOutput/RequireCheckedSyscalls.pm
lib/Perl/Critic/Policy/Miscellanea/ProhibitFormats.pm
lib/Perl/Critic/Policy/Miscellanea/ProhibitTies.pm
lib/Perl/Critic/Policy/Miscellanea/RequireRcsKeywords.pm
lib/Perl/Critic/Policy/Modules/ProhibitAutomaticExportation.pm
lib/Perl/Critic/Policy/Modules/ProhibitEvilModules.pm
lib/Perl/Critic/Policy/Modules/ProhibitExcessMainComplexity.pm
lib/Perl/Critic/Policy/Modules/ProhibitMultiplePackages.pm
lib/Perl/Critic/Policy/Modules/RequireBarewordIncludes.pm
lib/Perl/Critic/Policy/Modules/RequireEndWithOne.pm
lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm
lib/Perl/Critic/Policy/Modules/RequireFilenameMatchesPackage.pm
lib/Perl/Critic/Policy/Modules/RequireNoMatchVarsWithUseEnglish.pm
lib/Perl/Critic/Policy/Modules/RequireVersionVar.pm
lib/Perl/Critic/Policy/NamingConventions/ProhibitAmbiguousNames.pm
lib/Perl/Critic/Policy/NamingConventions/ProhibitMixedCaseSubs.pm
lib/Perl/Critic/Policy/NamingConventions/ProhibitMixedCaseVars.pm
lib/Perl/Critic/Policy/References/ProhibitDoubleSigils.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitCaptureWithoutTest.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitComplexRegexes.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitEnumeratedClasses.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitEscapedMetacharacters.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitFixedStringMatches.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitSingleCharAlternation.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitUnusedCapture.pm
lib/Perl/Critic/Policy/RegularExpressions/ProhibitUnusualDelimiters.pm
lib/Perl/Critic/Policy/RegularExpressions/RequireBracesForMultiline.pm
lib/Perl/Critic/Policy/RegularExpressions/RequireExtendedFormatting.pm
lib/Perl/Critic/Policy/RegularExpressions/RequireLineBoundaryMatching.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitAmpersandSigils.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitBuiltinHomonyms.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitExcessComplexity.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitExplicitReturnUndef.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitManyArgs.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitNestedSubs.pm
lib/Perl/Critic/Policy/Subroutines/ProhibitSubroutinePrototypes.pm
lib/Perl/Critic/Policy/Subroutines/ProtectPrivateSubs.pm
lib/Perl/Critic/Policy/Subroutines/RequireArgUnpacking.pm
lib/Perl/Critic/Policy/Subroutines/RequireFinalReturn.pm
lib/Perl/Critic/Policy/TestingAndDebugging/ProhibitNoStrict.pm
lib/Perl/Critic/Policy/TestingAndDebugging/ProhibitNoWarnings.pm
lib/Perl/Critic/Policy/TestingAndDebugging/ProhibitProlongedStrictureOverride.pm
lib/Perl/Critic/Policy/TestingAndDebugging/RequireTestLabels.pm
lib/Perl/Critic/Policy/TestingAndDebugging/RequireUseStrict.pm
lib/Perl/Critic/Policy/TestingAndDebugging/RequireUseWarnings.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitCommaSeparatedStatements.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitConstantPragma.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitEmptyQuotes.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitEscapedCharacters.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitImplicitNewlines.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitInterpolationOfLiterals.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitLeadingZeros.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitLongChainsOfMethodCalls.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitMagicNumbers.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitMismatchedOperators.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitMixedBooleanOperators.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitNoisyQuotes.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitQuotesAsQuotelikeOperatorDelimiters.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitVersionStrings.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/RequireInterpolationOfMetachars.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/RequireNumberSeparators.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/RequireQuotedHeredocTerminator.pm
lib/Perl/Critic/Policy/ValuesAndExpressions/RequireUpperCaseHeredocTerminator.pm
lib/Perl/Critic/Policy/Variables/ProhibitConditionalDeclarations.pm
lib/Perl/Critic/Policy/Variables/ProhibitLocalVars.pm
lib/Perl/Critic/Policy/Variables/ProhibitMatchVars.pm
lib/Perl/Critic/Policy/Variables/ProhibitPackageVars.pm
lib/Perl/Critic/Policy/Variables/ProhibitPerl4PackageNames.pm
lib/Perl/Critic/Policy/Variables/ProhibitPunctuationVars.pm
lib/Perl/Critic/Policy/Variables/ProhibitUnusedVariables.pm
lib/Perl/Critic/Policy/Variables/ProtectPrivateVars.pm
lib/Perl/Critic/Policy/Variables/RequireInitializationForLocalVars.pm
lib/Perl/Critic/Policy/Variables/RequireLexicalLoopIterators.pm
lib/Perl/Critic/Policy/Variables/RequireLocalizedPunctuationVars.pm
lib/Perl/Critic/Policy/Variables/RequireNegativeIndices.pm
lib/Perl/Critic/PolicyFactory.pm
lib/Perl/Critic/PolicyListing.pm
lib/Perl/Critic/PolicyParameter.pm
lib/Perl/Critic/PolicyParameter/Behavior.pm
lib/Perl/Critic/PolicyParameter/Behavior/Boolean.pm
lib/Perl/Critic/PolicyParameter/Behavior/Enumeration.pm
lib/Perl/Critic/PolicyParameter/Behavior/Integer.pm
lib/Perl/Critic/PolicyParameter/Behavior/String.pm
lib/Perl/Critic/PolicyParameter/Behavior/StringList.pm
lib/Perl/Critic/PolicySummary.pod.PL
lib/Perl/Critic/ProfilePrototype.pm
lib/Perl/Critic/TestUtils.pm
lib/Perl/Critic/Theme.pm
lib/Perl/Critic/ThemeListing.pm
lib/Perl/Critic/UserProfile.pm
lib/Perl/Critic/Utils.pm
lib/Perl/Critic/Utils/Constants.pm
lib/Perl/Critic/Utils/McCabe.pm
lib/Perl/Critic/Utils/POD.pm
lib/Perl/Critic/Utils/PPI.pm
lib/Perl/Critic/Utils/PPIRegexp.pm
lib/Perl/Critic/Violation.pm
tools/ppidump

index 5754eea..9680e3f 100644 (file)
--- a/TODO.pod
+++ b/TODO.pod
@@ -65,7 +65,8 @@ Requires C<## no critic> to take an argument:
   ## no critic (SomePolicyPattern)     # ok
   ## no critic                         # not ok
 
-Can't be done as a regular Policy because any line that violated it would disable it.
+Can't be done as a regular Policy because any line that violated it would
+disable it.
 
 
 =item * Support for C<#line 123 "filename"> directives.
@@ -134,7 +135,8 @@ difference between that and C<< $self->_foo() >>
 This should not complain about using C<warn> or C<die> if it's not in a
 function, or if it's in main::.
 
-Also, should allow C<die> when it is obvious that the "message" is a reference.
+Also, should allow C<die> when it is obvious that the "message" is a
+reference.
 
 
 =item * RegularExpressions::ProhibitCaptureWithoutTest
@@ -151,6 +153,7 @@ Allow this construct:
 Right now, P::C thinks that the C<$1> isn't legal to use because it's
 "outside" of the match.  The thing is, we can only get to the C<if>
 if the regex matched.
+
     while ( $str =~ /(expression)/ )
 
 
@@ -236,12 +239,13 @@ See L<http://use.perl.org/~Ovid/journal/36767>.
 
 =item * InputOutput::ProhibitMagicDiamond
 
-Steal the idea from L<B::Lint>.
+Steal the idea from L<B::Lint|B::Lint>.
 
 
 =item * TBD::AllProgramsNeedShebangs
 
-Anything that is a program should have a shebang line.  This includes .t files.
+Anything that is a program should have a shebang line.  This includes .t
+files.
 
 
 =item * BuiltInFunctions::RequireConstantSprintfFormat
@@ -286,15 +290,14 @@ Forbid C<do "foo.pl">.  Not sure about this policy name.
 =item * Variables::ProhibitUseVars
 
 Disallow C<use vars qw(...)> and require C<our $foo> instead.  This
-contradicts Miscellanea::Prohibit5006isms.  Maybe verify C<use 5.6>
-before applying this policy.  Low severity.
+contradicts Miscellanea::Prohibit5006isms.  Maybe verify C<use 5.6> before
+applying this policy.  Low severity.
 
 
 =item * VariablesAndExpressions::ProhibitQuotedHashKeys
 
-Forbid quotes around hash keys, unless they are really needed.  This
-is against what Damian says.  Suggested by Adam Kennedy.  Low
-severity.
+Forbid quotes around hash keys, unless they are really needed.  This is
+against what Damian says.  Suggested by Adam Kennedy.  Low severity.
 
 
 =item * CodeLayout::ProhibitFunctionalNew
@@ -340,8 +343,7 @@ content.
 
 =item * Miscellaneous::ProhibitBoilerplate
 
-Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
-etc.
+Complain about copy-and-paste code or docs from h2xs, Module::Starter::*, etc.
 
 Here's a non-PPI implementation:
 L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
@@ -388,7 +390,8 @@ for performance gains and compile-time syntax checking.
 
 =item * RegularExpressions::ProhibitUnnecessaryEscapes
 
-Complain if user puts a backslash escape in front of non-special characters.  For example:
+Complain if user puts a backslash escape in front of non-special characters.
+For example:
 
    m/\!/;
 
@@ -398,10 +401,10 @@ workaround bugs in syntax highlighting.
 Note that this is different inside character classes, where only C<^>, C<]>
 and C<-> need to be escaped, I think.  Caret only needs to be escaped at the
 beginning, and dash does NOT need to be escaped at the beginning and end.  See
-L<perlreref>.
+L<perlreref|perlreref>.
 
 
-=item * Steal ideas from L<Dunce::Files>.
+=item * Steal ideas from L<Dunce::Files|Dunce::Files>.
 
 Can someone expand this entry, please?
 
@@ -488,24 +491,24 @@ Just like F<bin/perlcritic> does now.
 
 =item * Add C<-cache> flag to F<bin/perlcritic>
 
-If enabled, this turns on L<PPI::Cache>:
+If enabled, this turns on L<PPI::Cache|PPI::Cache>:
 
     require PPI::Cache;
     my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
     mkdir $cache_path, oct 700 if (! -d $cache_path);
     PPI::Cache->import(path => $cache_path);
 
-This cachedir should perhaps include the PPI version number!  At least
-until PPI incorporates its own version number in the cache.
+This cachedir should perhaps include the PPI version number!  At least until
+PPI incorporates its own version number in the cache.
 
 (see F<t/40_criticize.t> for a more robust implementation)
 
 
 =item * Use hash-lookup instead of C<List::MoreUtils::any> function.
 
-In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
-a string is a member of a list.  Instead, I suggest using a named
-subroutine that does a hash-lookup like this:
+In several places, Perl::Critic uses C<List::MoreUtils::any> to see if a
+string is a member of a list.  Instead, I suggest using a named subroutine
+that does a hash-lookup like this:
 
     my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
     sub is_logical_op { return exists $logical_ops{ $_[0] }; }
@@ -545,10 +548,9 @@ It's unlikely that PPI will support mixde newlines anytime soon.
 
 =item Operators
 
-ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
-for PPI bugs with parsing operators.  Many of these bugs have been
-fixed in PPI, so it would be good to check if those workarounds are
-still needed.
+ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds for PPI
+bugs with parsing operators.  Many of these bugs have been fixed in PPI, so it
+would be good to check if those workarounds are still needed.
 
 
 =item Regexp methods
index 1c7504a..36ec234 100755 (executable)
@@ -540,6 +540,7 @@ screenshots tty emacs gVIM plugin Perlish templating ActiveState
 
 C<perlcritic> - Command-line interface to critique Perl source.
 
+
 =head1 SYNOPSIS
 
   perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle]
@@ -556,20 +557,22 @@ C<perlcritic> - Command-line interface to critique Perl source.
 
   perlcritic { --help | --options | --man | --version }
 
+
 =head1 DESCRIPTION
 
 C<perlcritic> is a Perl source code analyzer.  It is the executable
-front-end to the L<Perl::Critic> engine, which attempts to identify
-awkward, hard to read, error-prone, or unconventional constructs in
-your code.  Most of the rules are based on Damian Conway's book B<Perl
-Best Practices>.  However, C<perlcritic> is B<not> limited to
-enforcing PBP, and it will even support rules that contradict Conway.
-All rules can easily be configured or disabled to your liking.
+front-end to the L<Perl::Critic|Perl::Critic> engine, which attempts
+to identify awkward, hard to read, error-prone, or unconventional
+constructs in your code.  Most of the rules are based on Damian
+Conway's book B<Perl Best Practices>.  However, C<perlcritic> is
+B<not> limited to enforcing PBP, and it will even support rules that
+contradict Conway.  All rules can easily be configured or disabled to
+your liking.
 
 This documentation only covers how to drive this command.  For all
 other information, including how to persistently configure this
-command so that you don't have to say so much on the command-line,
-see the documentation for L<Perl::Critic> itself.
+command so that you don't have to say so much on the command-line, see
+the documentation for L<Perl::Critic|Perl::Critic> itself.
 
 
 =head1 USAGE EXAMPLES
@@ -577,90 +580,94 @@ see the documentation for L<Perl::Critic> itself.
 Before getting into all the gory details, here are some basic usage
 examples to help get you started.
 
-  # Report only most severe violations (severity = 5)
-  perlcritic YourModule.pm
+    # Report only most severe violations (severity = 5)
+    perlcritic YourModule.pm
+
+    # Same as above, but read input from STDIN
+    perlcritic
 
-  # Same as above, but read input from STDIN
-  perlcritic
+    # Recursively process all Perl files beneath directory
+    perlcritic /some/directory
 
-  # Recursively process all Perl files beneath directory
-  perlcritic /some/directory
+    # Report slightly less severe violations too (severity >= 4)
+    perlcritic -4 YourModule.pm
 
-  # Report slightly less severe violations too (severity >= 4)
-  perlcritic -4 YourModule.pm
+    # Same as above, but using named severity level
+    perlcritic --stern YourModule.pm
 
-  # Same as above, but using named severity level
-  perlcritic --stern YourModule.pm
+    # Report all violations, regardless of severity (severity >= 1)
+    perlcritic -1 YourModule.pm
 
-  # Report all violations, regardless of severity (severity >= 1)
-  perlcritic -1 YourModule.pm
+    # Same as above, but using named severity level
+    perlcritic --brutal YourModule.pm
 
-  # Same as above, but using named severity level
-  perlcritic --brutal YourModule.pm
+    # Report only violations of things from "Perl Best Practices"
+    perlcritic --theme pbp YourModule.pm
 
-  # Report only violations of things from "Perl Best Practices"
-  perlcritic --theme pbp YourModule.pm
+    # Report top 20 most severe violations (severity >= 1)
+    perlcritic --top YourModule.pm
 
-  # Report top 20 most severe violations (severity >= 1)
-  perlcritic --top YourModule.pm
+    # Report additional violations of Policies that match m/variables/ix
+    perlcritic --include variables YourModule.pm
 
-  # Report additional violations of Policies that match m/variables/ix
-  perlcritic --include variables YourModule.pm
+    # Use defaults from somewhere other than ~/.perlcriticrc
+    perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
 
-  # Use defaults from somewhere other than ~/.perlcriticrc
-  perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
 
 =head1 ARGUMENTS
 
 The arguments are paths to the files you wish to analyze.  You may
 specify multiple files.  If an argument is a directory, C<perlcritic>
-will analyze all Perl files below the directory.  If no arguments
-are specified, then input is read from STDIN.
+will analyze all Perl files below the directory.  If no arguments are
+specified, then input is read from STDIN.
+
 
 =head1 OPTIONS
 
 Option names can be abbreviated to uniqueness and can be stated with
 singe or double dashes, and option values can be separated from the
-option name by a space or '=' (as with L<Getopt::Long>).  Option names
-are also case-sensitive.
+option name by a space or '=' (as with L<Getopt::Long|Getopt::Long>).
+Option names are also case-sensitive.
 
 =over 8
 
 =item C<--profile FILE>
 
-Directs C<perlcritic> to use a profile named by FILE rather than looking
-for the default F<.perlcriticrc> file in the current directory or your
-home directory.  See L<Perl::Critic/"CONFIGURATION"> for more information.
+Directs C<perlcritic> to use a profile named by FILE rather than
+looking for the default F<.perlcriticrc> file in the current directory
+or your home directory.  See L<Perl::Critic/"CONFIGURATION"> for more
+information.
 
 =item C<--noprofile>
 
-Directs C<perlcritic> not to load any configuration file, thus reverting
-to the default configuration for all Policies.
+Directs C<perlcritic> not to load any configuration file, thus
+reverting to the default configuration for all Policies.
 
 =item C<--severity N>
 
-Directs C<perlcritic> to only apply Policies with a severity greater than
-C<N>.  Severity values are integers ranging from 1 (least severe) to 5 (most
-severe).  The default is 5.  For a given C<--profile>, decreasing the
-C<--severity> will usually produce more violations.  You can set the default
-value for this option in your F<.perlcriticrc> file.  You can also redefine
-the C<severity> for any Policy in your F<.perlcriticrc> file.  See
-L<"CONFIGURATION"> for more information.
+Directs C<perlcritic> to only apply Policies with a severity greater
+than C<N>.  Severity values are integers ranging from 1 (least severe)
+to 5 (most severe).  The default is 5.  For a given C<--profile>,
+decreasing the C<--severity> will usually produce more violations.
+You can set the default value for this option in your F<.perlcriticrc>
+file.  You can also redefine the C<severity> for any Policy in your
+F<.perlcriticrc> file.  See L<"CONFIGURATION"> for more information.
 
 =item C<-5 | -4 | -3 | -2 | -1>
 
-These are numeric shortcuts for setting the C<--severity> option.  For example,
-C<"-4"> is equivalent to C<"--severity 4">.  If multiple shortcuts are
-specified, then the most restrictive one wins.  If an explicit C<--severity>
-option is also given, then all shortcut options are silently ignored.  NOTE:
-Be careful not to put one of the number severity shortcut options immediately
-after the C<--top> flag or C<perlcritic> will interpret it as the number of
-violations to report.
+These are numeric shortcuts for setting the C<--severity> option.  For
+example, C<"-4"> is equivalent to C<"--severity 4">.  If multiple
+shortcuts are specified, then the most restrictive one wins.  If an
+explicit C<--severity> option is also given, then all shortcut options
+are silently ignored.  NOTE: Be careful not to put one of the number
+severity shortcut options immediately after the C<--top> flag or
+C<perlcritic> will interpret it as the number of violations to report.
 
 =item C<--severity NAME>
 
-If it is difficult for you to remember whether severity "5" is the most
-or least restrictive level, then you can use one of these named values:
+If it is difficult for you to remember whether severity "5" is the
+most or least restrictive level, then you can use one of these named
+values:
 
     SEVERITY NAME   ...is equivalent to...   SEVERITY NUMBER
     --------------------------------------------------------
@@ -672,220 +679,236 @@ or least restrictive level, then you can use one of these named values:
 
 =item C<--gentle | --stern | --harsh | --cruel | --brutal>
 
-These are named shortcuts for setting the C<--severity> option.  For example,
-C<"--cruel"> is equivalent to C<"--severity 2">.  If multiple shortcuts are
-specified, then the most restrictive one wins.  If an explicit C<--severity>
-option is also given, then all shortcut options are silently ignored.
+These are named shortcuts for setting the C<--severity> option.  For
+example, C<"--cruel"> is equivalent to C<"--severity 2">.  If multiple
+shortcuts are specified, then the most restrictive one wins.  If an
+explicit C<--severity> option is also given, then all shortcut options
+are silently ignored.
 
 =item C<--theme RULE>
 
-Directs C<perlcritic> to apply only Policies with themes that satisfy the
-C<RULE>.  Themes are arbitrary names for groups of related policies.  You can
-combine theme names with boolean operators to create an arbitrarily complex
-C<RULE>.  For example, the following would apply only Policies that have a
-'bugs' AND 'pbp' theme:
+Directs C<perlcritic> to apply only Policies with themes that satisfy
+the C<RULE>.  Themes are arbitrary names for groups of related
+policies.  You can combine theme names with boolean operators to
+create an arbitrarily complex C<RULE>.  For example, the following
+would apply only Policies that have a 'bugs' AND 'pbp' theme:
 
-  $> perlcritic --theme='bugs && pbp' MyModule.pm
+    $> perlcritic --theme='bugs && pbp' MyModule.pm
 
-Unless the C<--severity> option is explicitly given, setting C<--theme> silently
-causes the C<--severity> to be set to 1.  You can set the default value for
-this option in your F<.perlcriticrc> file.  See L<Perl::Critic/"POLICY THEMES">
-for more information about themes.
+Unless the C<--severity> option is explicitly given, setting
+C<--theme> silently causes the C<--severity> to be set to 1.  You can
+set the default value for this option in your F<.perlcriticrc> file.
+See L<Perl::Critic/"POLICY THEMES"> for more information about themes.
 
 =item C<--include PATTERN>
 
-Directs C<perlcritic> to apply additional Policies that match the regex
-C</PATTERN/imx>.  Use this option to temporarily override your profile and/or
-the severity settings at the command-line.  For example:
+Directs C<perlcritic> to apply additional Policies that match the
+regex C</PATTERN/imx>.  Use this option to temporarily override your
+profile and/or the severity settings at the command-line.  For
+example:
 
-  perlcritic --include=layout my_file.pl
+    perlcritic --include=layout my_file.pl
 
-This would cause C<perlcritic> to apply all the C<CodeLayout::*> policies even
-if they have a severity level that is less than the default level of 5, or
-have been disabled in your F<.perlcriticrc> file.  You can specify multiple
-C<--include> options and you can use it in conjunction with the C<--exclude>
-option.  Note that C<--exclude> takes precedence over C<--include> when a Policy
-matches both patterns.  You can set the default value for this option in your
+This would cause C<perlcritic> to apply all the C<CodeLayout::*>
+policies even if they have a severity level that is less than the
+default level of 5, or have been disabled in your F<.perlcriticrc>
+file.  You can specify multiple C<--include> options and you can use
+it in conjunction with the C<--exclude> option.  Note that
+C<--exclude> takes precedence over C<--include> when a Policy matches
+both patterns.  You can set the default value for this option in your
 F<.perlcriticrc> file.
 
 =item C<--exclude PATTERN>
 
 Directs C<perlcritic> to not apply any Policy that matches the regex
-C</PATTERN/imx>.  Use this option to temporarily override your profile and/or
-the severity settings at the command-line.  For example:
+C</PATTERN/imx>.  Use this option to temporarily override your profile
+and/or the severity settings at the command-line.  For example:
 
-  perlcritic --exclude=strict my_file.pl
+    perlcritic --exclude=strict my_file.pl
 
-This would cause C<perlcritic> to not apply the C<RequireUseStrict> and
-C<ProhibitNoStrict> Policies even though they have the highest severity level.
-You can specify multiple C<--exclude> options and you can use it in conjunction
-with the C<--include> option.  Note that C<--exclude> takes precedence over
-C<--include> when a Policy matches both patterns.  You can set the default
-value for this option in your F<.perlcriticrc> file.
+This would cause C<perlcritic> to not apply the C<RequireUseStrict>
+and C<ProhibitNoStrict> Policies even though they have the highest
+severity level.  You can specify multiple C<--exclude> options and you
+can use it in conjunction with the C<--include> option.  Note that
+C<--exclude> takes precedence over C<--include> when a Policy matches
+both patterns.  You can set the default value for this option in your
+F<.perlcriticrc> file.
 
 =item C<--single-policy PATTERN>
 
-Directs C<perlcritic> to apply just one Policy module matching the regex
-C</PATTERN/imx>, and exclude all other Policies.  This option has precedence
-over the C<--severity>, C<--theme>, C<--include>, C<--exclude>, and C<--only>
-options.  For example:
+Directs C<perlcritic> to apply just one Policy module matching the
+regex C</PATTERN/imx>, and exclude all other Policies.  This option
+has precedence over the C<--severity>, C<--theme>, C<--include>,
+C<--exclude>, and C<--only> options.  For example:
 
-  perlcritic --single-policy=nowarnings my_file.pl
+    perlcritic --single-policy=nowarnings my_file.pl
 
-This would cause C<perlcritic> to apply just the C<ProhibitNoWarnings> Policy,
-regardless of the severity level setting.  No other Policies would be applied.
+This would cause C<perlcritic> to apply just the C<ProhibitNoWarnings>
+Policy, regardless of the severity level setting.  No other Policies
+would be applied.
 
 This is equivalent to what one might intend by...
 
-  perlcritic --exclude=. --include=nowarnings my_file.pl
+    perlcritic --exclude=. --include=nowarnings my_file.pl
 
 ... but this won't work because the C<--exclude> option overrides the
 C<--include> option.
 
-The equivalent of this option can be accomplished by creating a custom profile
-containing only the desired policy and then running...
+The equivalent of this option can be accomplished by creating a custom
+profile containing only the desired policy and then running...
 
-  perlcritic --profile=customprofile --only my_file.pl
+    perlcritic --profile=customprofile --only my_file.pl
 
 =item C<--top [ N ]>
 
-Directs C<perlcritic> to report only the top C<N> Policy violations in each
-file, ranked by their severity.  If C<N> is not specified, it defaults to 20.
-If the C<--severity> option (or one of the shortcuts) is not explicitly given,
-the C<--top> option implies that the minimum severity level is "1"
-(i.e. "brutal"). Users can redefine the severity for any Policy in their
-F<.perlcriticrc> file.  See L<"CONFIGURATION"> for more information.  You can
-set the default value for this option in your F<.perlcriticrc> file.  NOTE: Be
-careful not to put one of the severity shortcut options immediately after the
-C<--top> flag or C<perlcritic> will interpret it as the number of violations to
-report.
+Directs C<perlcritic> to report only the top C<N> Policy violations in
+each file, ranked by their severity.  If C<N> is not specified, it
+defaults to 20.  If the C<--severity> option (or one of the shortcuts)
+is not explicitly given, the C<--top> option implies that the minimum
+severity level is "1" (i.e. "brutal"). Users can redefine the severity
+for any Policy in their F<.perlcriticrc> file.  See L<"CONFIGURATION">
+for more information.  You can set the default value for this option
+in your F<.perlcriticrc> file.  NOTE: Be careful not to put one of the
+severity shortcut options immediately after the C<--top> flag or
+C<perlcritic> will interpret it as the number of violations to report.
 
 =item C<--force>
 
-Directs C<perlcritic> to ignore the magical C<"## no critic"> pseudo-pragmas
-in the source code. See L<"BENDING THE RULES"> for more information.  You can
-set the default value for this option in your F<.perlcriticrc> file.
+Directs C<perlcritic> to ignore the magical C<"## no critic">
+pseudo-pragmas in the source code. See L<"BENDING THE RULES"> for more
+information.  You can set the default value for this option in your
+F<.perlcriticrc> file.
 
 =item C<--statistics>
 
-Causes several statistics about the code being scanned and the violations
-found to be reported after any other output.
+Causes several statistics about the code being scanned and the
+violations found to be reported after any other output.
 
 =item C<--statistics-only>
 
-Like the C<--statistics> option, but suppresses normal output and only shows
-the statistics.
+Like the C<--statistics> option, but suppresses normal output and only
+shows the statistics.
 
 =item C<--verbose N | FORMAT>
 
-Sets the verbosity level or format for reporting violations.  If given a
-number (C<N>), C<perlcritic> reports violations using one of the predefined
-formats described below.  If given a string (C<FORMAT>), it is interpreted to
-be an actual format specification.  If the C<--verbose> option is not
-specified, it defaults to either 4 or 5, depending on whether multiple files
-were given as arguments to C<perlcritic>.  You can set the default value for
-this option in your F<.perlcriticrc> file.
-
-  Verbosity     Format Specification
-  -----------   -------------------------------------------------------------
-   1            "%f:%l:%c:%m\n",
-   2            "%f: (%l:%c) %m\n",
-   3            "%m at %f line %l\n",
-   4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
-   5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
-   6            "%m at line %l, near '%r'.  (Severity: %s)\n",
-   7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
-   8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
-   9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
-  10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
-  11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
-
-Formats are a combination of literal and escape characters similar to the way
-C<sprintf> works.  See L<String::Format> for a full explanation of the
-formatting capabilities.  Valid escape characters are:
-
-  Escape    Meaning
-  -------   ----------------------------------------------------------------
-  %c        Column number where the violation occurred
-  %d        Full diagnostic discussion of the violation
-  %e        Explanation of violation or page numbers in PBP
-  %F        Just the name of the file where the violation occurred.
-  %f        Path to the file where the violation occurred.
-  %l        Line number where the violation occurred
-  %m        Brief description of the violation
-  %P        Full name of the Policy module that created the violation
-  %p        Name of the Policy without the Perl::Critic::Policy:: prefix
-  %r        The string of source code that caused the violation
-  %s        The severity level of the violation
-
-The purpose of these formats is to provide some compatibility with text
-editors that have an interface for parsing certain kinds of input. See
-L<"EDITOR INTEGRATION"> for more information about that.
+Sets the verbosity level or format for reporting violations.  If given
+a number (C<N>), C<perlcritic> reports violations using one of the
+predefined formats described below.  If given a string (C<FORMAT>), it
+is interpreted to be an actual format specification.  If the
+C<--verbose> option is not specified, it defaults to either 4 or 5,
+depending on whether multiple files were given as arguments to
+C<perlcritic>.  You can set the default value for this option in your
+F<.perlcriticrc> file.
+
+    Verbosity     Format Specification
+    -----------   -------------------------------------------------------
+     1            "%f:%l:%c:%m\n",
+     2            "%f: (%l:%c) %m\n",
+     3            "%m at %f line %l\n",
+     4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
+     5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
+     6            "%m at line %l, near '%r'.  (Severity: %s)\n",
+     7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
+     8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
+     9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
+    10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
+    11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
+
+Formats are a combination of literal and escape characters similar to
+the way C<sprintf> works.  See L<String::Format|String::Format> for a
+full explanation of the formatting capabilities.  Valid escape
+characters are:
+
+    Escape    Meaning
+    -------   ------------------------------------------------------------
+    %c        Column number where the violation occurred
+    %d        Full diagnostic discussion of the violation
+    %e        Explanation of violation or page numbers in PBP
+    %F        Just the name of the file where the violation occurred.
+    %f        Path to the file where the violation occurred.
+    %l        Line number where the violation occurred
+    %m        Brief description of the violation
+    %P        Full name of the Policy module that created the violation
+    %p        Name of the Policy without the Perl::Critic::Policy:: prefix
+    %r        The string of source code that caused the violation
+    %s        The severity level of the violation
+
+The purpose of these formats is to provide some compatibility with
+text editors that have an interface for parsing certain kinds of
+input. See L<"EDITOR INTEGRATION"> for more information about that.
 
 =item C<--list>
 
-Displays a condensed listing of all the L<Perl::Critic::Policy> modules that
-are found on this machine.  For each Policy, the name, default severity and
-default themes are shown.
+Displays a condensed listing of all the
+L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
+this machine.  For each Policy, the name, default severity and default
+themes are shown.
 
 =item C<--list-themes>
 
-Displays a list of all the themes of the L<Perl::Critic::Policy> modules that
-are found on this machine.
+Displays a list of all the themes of the
+L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
+this machine.
 
 =item C<--profile-proto>
 
-Displays an expanded listing of all the L<Perl::Critic::Policy> modules that
-are found on this machine.  For each Policy, the name, default severity and
-default themes are shown, as well as the name of any additional parameters
-that the Policy supports.  The format is suitable as a prototype for your
-F<.perlcriticrc> file.
+Displays an expanded listing of all the
+L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
+this machine.  For each Policy, the name, default severity and default
+themes are shown, as well as the name of any additional parameters
+that the Policy supports.  The format is suitable as a prototype for
+your F<.perlcriticrc> file.
 
 =item C<--only>
 
-Directs perlcritic to apply only Policies that are explicitly mentioned in
-your F<.perlcriticrc> file.  This is useful if you want to use just a small
-subset of Policies without having to disable all the others.  You can set the
-default value for this option in your F<.perlcriticrc> file.
+Directs perlcritic to apply only Policies that are explicitly
+mentioned in your F<.perlcriticrc> file.  This is useful if you want
+to use just a small subset of Policies without having to disable all
+the others.  You can set the default value for this option in your
+F<.perlcriticrc> file.
 
 =item C<--profile-strictness {warn|fatal|quiet}>
 
-Directs perlcritic how to treat certain recoverable problems found in a
-F<.perlcriticrc> or file specified via the C<--profile> option.  Valid values
-are C<warn> (the default), C<fatal>, and C<quiet>.  For example, perlcritic
-normally only warns about profiles referring to non-existent Policies, but
-this option can make this situation fatal.  You can set the default value for
-this option in your F<.perlcriticrc> file.
+Directs perlcritic how to treat certain recoverable problems found in
+a F<.perlcriticrc> or file specified via the C<--profile> option.
+Valid values are C<warn> (the default), C<fatal>, and C<quiet>.  For
+example, perlcritic normally only warns about profiles referring to
+non-existent Policies, but this option can make this situation fatal.
+You can set the default value for this option in your F<.perlcriticrc>
+file.
 
 =item C<--count>
 
 =item C<-C>
 
-Display only the number of violations for each file.  Use this feature to get
-a quick handle on where a large pile of code might need the most attention.
+Display only the number of violations for each file.  Use this feature
+to get a quick handle on where a large pile of code might need the
+most attention.
 
 =item C<--Safari>
 
 Report "Perl Best Practice" citations as section numbers from
-L<http://safari.oreilly.com> instead of page numbers from the actual book.
-NOTE: This feature is not implemented yet.
+L<http://safari.oreilly.com> instead of page numbers from the actual
+book.  NOTE: This feature is not implemented yet.
 
 =item C<--color>
 
-This option is on by default.  When set, Severity 5 and 4 are colored red and
-yellow, respectively.  Colorization only happens if STDOUT is a tty and
-L<Term::ANSIColor> is installed.  And it only works on non-Windows
-environments.  Negate this switch to disable color.  You can set the default
-value for this option in your F<.perlcriticrc> file.
+This option is on by default.  When set, Severity 5 and 4 are colored
+red and yellow, respectively.  Colorization only happens if STDOUT is
+a tty and L<Term::ANSIColor|Term::ANSIColor> is installed.  And it
+only works on non-Windows environments.  Negate this switch to disable
+color.  You can set the default value for this option in your
+F<.perlcriticrc> file.
 
 Can also be specified as C<--colour>.
 
 =item C<--doc PATTERN>
 
-Displays the perldoc for all L<Perl::Critic::Policy> modules that match
-C<m/PATTERN/imx>.  Since Policy modules tend to have rather long names, this
-just provides a more convenient way to say something like: C<"perldoc
-Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator">
+Displays the perldoc for all
+L<Perl::Critic::Policy|Perl::Critic::Policy> modules that match
+C<m/PATTERN/imx>.  Since Policy modules tend to have rather long
+names, this just provides a more convenient way to say something like:
+C<"perldoc Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator">
 at the command prompt.
 
 =item C<--quiet>
@@ -902,8 +925,8 @@ Displays a brief summary of options and exits.
 
 =item C<--options>
 
-Displays the descriptions of the options and exits.  While this output is
-long, it it nowhere near the length of the output of C<--man>.
+Displays the descriptions of the options and exits.  While this output
+is long, it it nowhere near the length of the output of C<--man>.
 
 =item C<--man>
 
@@ -919,191 +942,203 @@ Displays the version number of C<perlcritic> and exits.
 
 =head1 CONFIGURATION
 
-Most of the settings for Perl::Critic and each of the Policy modules can be
-controlled by a configuration file.  The default configuration file is called
-F<.perlcriticrc>.  C<perlcritic> will look for this file in the current
-directory first, and then in your home directory.  Alternatively, you can set
-the C<PERLCRITIC> environment variable to explicitly point to a different file
-in another location.  If none of these files exist, and the C<--profile> option
-is not given on the command-line, then all Policies will be loaded with their
-default configuration.
-
-The format of the configuration file is a series of INI-style blocks that
-contain key-value pairs separated by "=". Comments should start with "#" and
-can be placed on a separate line or after the name-value pairs if you desire.
-
-Default settings for perlcritic itself can be set B<before the first named
-block.> For example, putting any or all of these at the top of your
-F<.perlcriticrc> file will set the default value for the corresponding
-command-line argument.
-
-  severity  = 3                                     #Integer or named level
-  only      = 1                                     #Zero or One
-  force     = 0                                     #Zero or One
-  verbose   = 4                                     #Integer or format spec
-  top       = 50                                    #A positive integer
-  theme     = (pbp + security) * bugs               #A theme expression
-  include   = NamingConventions ClassHierarchies    #Space-delimited list
-  exclude   = Variables  Modules::RequirePackage    #Space-delimited list
+Most of the settings for Perl::Critic and each of the Policy modules
+can be controlled by a configuration file.  The default configuration
+file is called F<.perlcriticrc>.  C<perlcritic> will look for this
+file in the current directory first, and then in your home directory.
+Alternatively, you can set the C<PERLCRITIC> environment variable to
+explicitly point to a different file in another location.  If none of
+these files exist, and the C<--profile> option is not given on the
+command-line, then all Policies will be loaded with their default
+configuration.
+
+The format of the configuration file is a series of INI-style blocks
+that contain key-value pairs separated by "=". Comments should start
+with "#" and can be placed on a separate line or after the name-value
+pairs if you desire.
+
+Default settings for perlcritic itself can be set B<before the first
+named block.> For example, putting any or all of these at the top of
+your F<.perlcriticrc> file will set the default value for the
+corresponding command-line argument.
+
+    severity  = 3                                     #Integer or named level
+    only      = 1                                     #Zero or One
+    force     = 0                                     #Zero or One
+    verbose   = 4                                     #Integer or format spec
+    top       = 50                                    #A positive integer
+    theme     = (pbp + security) * bugs               #A theme expression
+    include   = NamingConventions ClassHierarchies    #Space-delimited list
+    exclude   = Variables  Modules::RequirePackage    #Space-delimited list
 
 The remainder of the configuration file is a series of blocks like this:
 
-  [Perl::Critic::Policy::Category::PolicyName]
-  severity = 1
-  set_themes = foo bar
-  add_themes = baz
-  arg1 = value1
-  arg2 = value2
-
-C<Perl::Critic::Policy::Category::PolicyName> is the full name of a module
-that implements the policy.  The Policy modules distributed with Perl::Critic
-have been grouped into categories according to the table of contents in Damian
-Conway's book B<Perl Best Practices>. For brevity, you can omit the
-C<'Perl::Critic::Policy'> part of the module name.
-
-C<severity> is the level of importance you wish to assign to the Policy.  All
-Policy modules are defined with a default severity value ranging from 1 (least
-severe) to 5 (most severe).  However, you may disagree with the default
-severity and choose to give it a higher or lower severity, based on your own
-coding philosophy.  You can set the C<severity> to an integer from 1 to 5, or
-use one of the equivalent names:
-
-  SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
-  ----------------------------------------------------
-  gentle                                             5
-  stern                                              4
-  harsh                                              3
-  cruel                                              2
-  brutal                                             1
-
-C<set_themes> sets the theme for the Policy and overrides its default theme.
-The argument is a string of one or more whitespace-delimited alphanumeric
-words.  Themes are case-insensitive.  See L<"POLICY THEMES"> for more
+    [Perl::Critic::Policy::Category::PolicyName]
+    severity = 1
+    set_themes = foo bar
+    add_themes = baz
+    arg1 = value1
+    arg2 = value2
+
+C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
+module that implements the policy.  The Policy modules distributed
+with Perl::Critic have been grouped into categories according to the
+table of contents in Damian Conway's book B<Perl Best Practices>. For
+brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
+name.
+
+C<severity> is the level of importance you wish to assign to the
+Policy.  All Policy modules are defined with a default severity value
+ranging from 1 (least severe) to 5 (most severe).  However, you may
+disagree with the default severity and choose to give it a higher or
+lower severity, based on your own coding philosophy.  You can set the
+C<severity> to an integer from 1 to 5, or use one of the equivalent
+names:
+
+    SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
+    ----------------------------------------------------
+    gentle                                             5
+    stern                                              4
+    harsh                                              3
+    cruel                                              2
+    brutal                                             1
+
+C<set_themes> sets the theme for the Policy and overrides its default
+theme.  The argument is a string of one or more whitespace-delimited
+alphanumeric words.  Themes are case-insensitive.  See L<"POLICY
+THEMES"> for more information.
+
+C<add_themes> appends to the default themes for this Policy.  The
+argument is a string of one or more whitespace-delimited words.
+Themes are case-insensitive.  See L<"POLICY THEMES"> for more
 information.
 
-C<add_themes> appends to the default themes for this Policy.  The argument is
-a string of one or more whitespace-delimited words.  Themes are
-case-insensitive.  See L<"POLICY THEMES"> for more information.
+The remaining key-value pairs are configuration parameters that will
+be passed into the constructor of that Policy.  The constructors for
+most Policy modules do not support arguments, and those that do should
+have reasonable defaults.  See the documentation on the appropriate
+Policy module for more details.
 
-The remaining key-value pairs are configuration parameters that will be passed
-into the constructor of that Policy.  The constructors for most Policy modules
-do not support arguments, and those that do should have reasonable defaults.
-See the documentation on the appropriate Policy module for more details.
-
-Instead of redefining the severity for a given Policy, you can completely
-disable a Policy by prepending a '-' to the name of the module in your
-configuration file.  In this manner, the Policy will never be loaded,
-regardless of the C<--severity> given on the command line.
+Instead of redefining the severity for a given Policy, you can
+completely disable a Policy by prepending a '-' to the name of the
+module in your configuration file.  In this manner, the Policy will
+never be loaded, regardless of the C<--severity> given on the command
+line.
 
 A simple configuration might look like this:
 
-  #--------------------------------------------------------------
-  # I think these are really important, so always load them
+    #--------------------------------------------------------------
+    # I think these are really important, so always load them
+
+    [TestingAndDebugging::RequireUseStrict]
+    severity = 5
 
-  [TestingAndDebugging::RequireUseStrict]
-  severity = 5
+    [TestingAndDebugging::RequireUseWarnings]
+    severity = 5
 
-  [TestingAndDebugging::RequireUseWarnings]
-  severity = 5
+    #--------------------------------------------------------------
+    # I think these are less important, so only load when asked
 
-  #--------------------------------------------------------------
-  # I think these are less important, so only load when asked
+    [Variables::ProhibitPackageVars]
+    severity = 2
 
-  [Variables::ProhibitPackageVars]
-  severity = 2
+    [ControlStructures::ProhibitPostfixControls]
+    allow = if unless  # My custom configuration
+    severity = cruel   # Same as "severity = 2"
 
-  [ControlStructures::ProhibitPostfixControls]
-  allow = if unless  # My custom configuration
-  severity = cruel   # Same as "severity = 2"
+    #--------------------------------------------------------------
+    # Give these policies a custom theme.  I can activate just
+    # these policies by saying "perlcritic --theme 'larry || curly'"
 
-  #--------------------------------------------------------------
-  # Give these policies a custom theme.  I can activate just
-  # these policies by saying "perlcritic --theme 'larry || curly'"
+    [Modules::RequireFilenameMatchesPackage]
+    add_themes = larry
 
-  [Modules::RequireFilenameMatchesPackage]
-  add_themes = larry
+    [TestingAndDebugging::RequireTestLabels]
+    add_themes = curly moe
 
-  [TestingAndDebugging::RequireTestLabels]
-  add_themes = curly moe
+    #--------------------------------------------------------------
+    # I do not agree with these at all, so never load them
 
-  #--------------------------------------------------------------
-  # I do not agree with these at all, so never load them
+    [-NamingConventions::ProhibitMixedCaseVars]
+    [-NamingConventions::ProhibitMixedCaseSubs]
 
-  [-NamingConventions::ProhibitMixedCaseVars]
-  [-NamingConventions::ProhibitMixedCaseSubs]
+    #--------------------------------------------------------------
+    # For all other Policies, I accept the default severity,
+    # so no additional configuration is required for them.
 
-  #--------------------------------------------------------------
-  # For all other Policies, I accept the default severity,
-  # so no additional configuration is required for them.
+Note that all policies included with the Perl::Critic distribution
+that have integer parameters accept underscores ("_") in their values,
+as with Perl numeric literals.  For example,
 
-Note that all policies included with the Perl::Critic distribution that have
-integer parameters accept underscores ("_") in their values, as with Perl
-numeric literals.  For example,
+    [ValuesAndExpressions::RequireNumberSeparators]
+    min_value = 1_000
 
-  [ValuesAndExpressions::RequireNumberSeparators]
-  min_value = 1_000
+For additional configuration examples, see the F<perlcriticrc> file
+that is included in this F<examples> directory of this distribution.
 
-For additional configuration examples, see the F<perlcriticrc> file that is
-included in this F<examples> directory of this distribution.
+Damian Conway's own Perl::Critic configuration is also included in
+this distribution as F<examples/perlcriticrc-conway>.
 
-Damian Conway's own Perl::Critic configuration is also included in this
-distribution as F<examples/perlcriticrc-conway>.
 
 =head1 THE POLICIES
 
-A large number of Policy modules are distributed with Perl::Critic.  They are
-described briefly in the companion document L<Perl::Critic::PolicySummary> and
-in more detail in the individual modules themselves.  Say C<"perlcritic --doc
-PATTERN"> to see the perldoc for all Policy modules that match the regex
-C<m/PATTERN/imx>
+A large number of Policy modules are distributed with Perl::Critic.
+They are described briefly in the companion document
+L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
+detail in the individual modules themselves.  Say C<"perlcritic --doc
+PATTERN"> to see the perldoc for all Policy modules that match the
+regex C<m/PATTERN/imx>
+
+There are a number of distributions of additional policies on CPAN.
+If L<Perl::Critic|Perl::Critic> doesn't contain a policy that you
+want, some one may have already written it.  See L<Perl::Critic/"SEE
+ALSO"> for a list of some of these distributions.
 
-There are a number of distributions of additional policies on CPAN.  If
-L<Perl::Critic> doesn't contain a policy that you want, some one may have
-already written it.  See L<Perl::Critic/"SEE ALSO"> for a list of some of
-these distributions.
 
 =head1 POLICY THEMES
 
-Each Policy is defined with one or more "themes".  Themes can be used to
-create arbitrary groups of Policies.  They are intended to provide an
-alternative mechanism for selecting your preferred set of Policies.  For
-example, you may wish disable a certain set of Policies when analyzing test
-scripts.  Conversely, you may wish to enable only a specific subset of
-Policies when analyzing modules.
-
-The Policies that ship with Perl::Critic are have been divided into the
-following themes.  This is just our attempt to provide some basic logical
-groupings.  You are free to invent new themes that suit your needs.
-
-  THEME             DESCRIPTION
-  --------------------------------------------------------------------------
-  core              All policies that ship with Perl::Critic
-  pbp               Policies that come directly from "Perl Best Practices"
-  bugs              Policies that that prevent or reveal bugs
-  maintenance       Policies that affect the long-term health of the code
-  cosmetic          Policies that only have a superficial effect
-  complexity        Policies that specificaly relate to code complexity
-  security          Policies that relate to security issues
-  tests             Policies that are specific to test scripts
-
-Say C<"perlcritic --list"> to get a listing of all available policies and the
-themes that are associated with each one.  You can also change the theme for
-any Policy in your F<.perlcriticrc> file.  See the L<"CONFIGURATION"> section
-for more information about that.
-
-Using the C<--theme> command-line option, you can create an arbitrarily complex
-rule that determines which Policies to apply.  Precedence is the same as
-regular Perl code, and you can use parentheses to enforce precedence as well.
-Supported operators are:
-
-  Operator    Altertative    Example
-  ----------------------------------------------------------------------------
-  &&          and            'pbp && core'
-  ||          or             'pbp || (bugs && security)'
-  !           not            'pbp && ! (portability || complexity)'
-
-Theme names are case-insensitive.  If the C<--theme> is set to an empty string,
-then it evaluates as true all Policies.
+Each Policy is defined with one or more "themes".  Themes can be used
+to create arbitrary groups of Policies.  They are intended to provide
+an alternative mechanism for selecting your preferred set of Policies.
+For example, you may wish disable a certain set of Policies when
+analyzing test scripts.  Conversely, you may wish to enable only a
+specific subset of Policies when analyzing modules.
+
+The Policies that ship with Perl::Critic are have been divided into
+the following themes.  This is just our attempt to provide some basic
+logical groupings.  You are free to invent new themes that suit your
+needs.
+
+    THEME             DESCRIPTION
+    ------------------------------------------------------------------------
+    core              All policies that ship with Perl::Critic
+    pbp               Policies that come directly from "Perl Best Practices"
+    bugs              Policies that that prevent or reveal bugs
+    maintenance       Policies that affect the long-term health of the code
+    cosmetic          Policies that only have a superficial effect
+    complexity        Policies that specificaly relate to code complexity
+    security          Policies that relate to security issues
+    tests             Policies that are specific to test scripts
+
+Say C<"perlcritic --list"> to get a listing of all available policies
+and the themes that are associated with each one.  You can also change
+the theme for any Policy in your F<.perlcriticrc> file.  See the
+L<"CONFIGURATION"> section for more information about that.
+
+Using the C<--theme> command-line option, you can create an
+arbitrarily complex rule that determines which Policies to apply.
+Precedence is the same as regular Perl code, and you can use
+parentheses to enforce precedence as well.  Supported operators are:
+
+    Operator    Altertative    Example
+    -----------------------------------------------------------------
+    &&          and            'pbp && core'
+    ||          or             'pbp || (bugs && security)'
+    !           not            'pbp && ! (portability || complexity)'
+
+Theme names are case-insensitive.  If the C<--theme> is set to an
+empty string, then it evaluates as true all Policies.
+
 
 =head1 BENDING THE RULES
 
@@ -1133,176 +1168,201 @@ certain lines or blocks of code by using pseudo-pragmas:
       do_something($_);
   }
 
-The C<"## no critic"> comments direct Perl::Critic to ignore the remaining
-lines of code until the end of the current block, or until a C<"## use
-critic"> comment is found (whichever comes first).  If the C<"## no critic">
-comment is on the same line as a code statement, then only that line of code
-is overlooked.  To direct perlcritic to ignore the C<"## no critic"> comments,
-use the C<--force> option.
+The C<"## no critic"> comments direct Perl::Critic to ignore the
+remaining lines of code until the end of the current block, or until a
+C<"## use critic"> comment is found (whichever comes first).  If the
+C<"## no critic"> comment is on the same line as a code statement,
+then only that line of code is overlooked.  To direct perlcritic to
+ignore the C<"## no critic"> comments, use the C<--force> option.
 
-A bare C<"## no critic"> comment disables all the active Policies.  If you
-wish to disable only specific Policies, add a list of Policy names as
-arguments just as you would for the C<"no strict"> or C<"no warnings"> pragma.
-For example, this would disable the C<ProhibitEmptyQuotes> and
-C<ProhibitPostfixControls> policies until the end of the block or until the
-next C<"## use critic"> comment (whichever comes first):
+A bare C<"## no critic"> comment disables all the active Policies.  If
+you wish to disable only specific Policies, add a list of Policy names
+as arguments just as you would for the C<"no strict"> or C<"no
+warnings"> pragma.  For example, this would disable the
+C<ProhibitEmptyQuotes> and C<ProhibitPostfixControls> policies until
+the end of the block or until the next C<"## use critic"> comment
+(whichever comes first):
 
-  ## no critic (EmptyQuotes, PostfixControls);
+    ## no critic (EmptyQuotes, PostfixControls);
 
-  # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
-  $foo = "";
+    # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
+    $foo = "";
 
-  # Now exempt ControlStructures::ProhibitPostfixControls
-  $barf = bar() if $foo;
+    # Now exempt ControlStructures::ProhibitPostfixControls
+    $barf = bar() if $foo;
 
-  # Still subject to ValuesAndExpression::RequireNumberSeparators
-  $long_int = 10000000000;
+    # Still subject to ValuesAndExpression::RequireNumberSeparators
+    $long_int = 10000000000;
 
-Since the Policy names are matched against the C<"## no critic"> arguments as
-regular expressions, you can abbreviate the Policy names or disable an entire
-family of Policies in one shot like this:
+Since the Policy names are matched against the C<"## no critic">
+arguments as regular expressions, you can abbreviate the Policy names
+or disable an entire family of Policies in one shot like this:
 
-  ## no critic (NamingConventions)
+    ## no critic (NamingConventions)
 
-  # Now exempt from NamingConventions::ProhibitMixedCaseVars
-  my $camelHumpVar = 'foo';
+    # Now exempt from NamingConventions::ProhibitMixedCaseVars
+    my $camelHumpVar = 'foo';
 
-  # Now exempt from NamingConventions::ProhibitMixedCaseSubs
-  sub camelHumpSub {}
+    # Now exempt from NamingConventions::ProhibitMixedCaseSubs
+    sub camelHumpSub {}
 
-The argument list must be enclosed in parentheses and must contain one or more
-comma-separated barewords (i.e. don't use quotes).  The C<"## no critic">
-pragmas can be nested, and Policies named by an inner pragma will be disabled
-along with those already disabled an outer pragma.
+The argument list must be enclosed in parentheses and must contain one
+or more comma-separated barewords (i.e. don't use quotes).  The C<"##
+no critic"> pragmas can be nested, and Policies named by an inner
+pragma will be disabled along with those already disabled an outer
+pragma.
 
-Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to an entire
-block of code.  In those cases, C<"## no critic"> must appear on the line
-where the violation is reported.  For example:
+Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to
+an entire block of code.  In those cases, C<"## no critic"> must
+appear on the line where the violation is reported.  For example:
 
-  sub complicated_function {  ## no critic (ProhibitExcessComplexity)
-      # Your code here...
-  }
+    sub complicated_function {  ## no critic (ProhibitExcessComplexity)
+        # Your code here...
+    }
+
+Some Policies like C<Documentation::RequirePodSections> apply to the
+entire document, in which case violations are reported at line 1.  But
+if the file requires a shebang line, it is impossible to put C<"## no
+critic"> on the first line of the file.  This is a known limitation
+and it will be addressed in a future release.  As a workaround, you
+can disable the affected policies at the command-line or in your
+F<.perlcriticrc> file.  But beware that this will affect the analysis
+of B<all> files.
 
-Some Policies like C<Documentation::RequirePodSections> apply to the entire
-document, in which case violations are reported at line 1.  But if the file
-requires a shebang line, it is impossible to put C<"## no critic"> on the
-first line of the file.  This is a known limitation and it will be addressed
-in a future release.  As a workaround, you can disable the affected policies
-at the command-line or in your F<.perlcriticrc> file.  But beware that this
-will affect the analysis of B<all> files.
+Use this feature wisely.  C<"## no critic"> should be used in the
+smallest possible scope, or only on individual lines of code. And you
+should always be as specific as possible about which policies you want
+to disable (i.e. never use a bare C<"## no critic">).  If Perl::Critic
+complains about your code, try and find a compliant solution before
+resorting to this feature.
 
-Use this feature wisely.  C<"## no critic"> should be used in the smallest
-possible scope, or only on individual lines of code. And you should always be
-as specific as possible about which policies you want to disable (i.e. never
-use a bare C<"## no critic">).  If Perl::Critic complains about your code, try
-and find a compliant solution before resorting to this feature.
 
 =head1 EDITOR INTEGRATION
 
-For ease-of-use, C<perlcritic> can be integrated with your favorite text
-editor.  The output-formatting capabilities of C<perlcritic> are specifically
-intended for use with the "grep" or "compile" modes available in editors like
-C<emacs> and C<vim>.  In these modes, you can run an arbitrary command and the
-editor will parse the output into an interactive buffer that you can click on
-and jump to the relevant line of code.
+For ease-of-use, C<perlcritic> can be integrated with your favorite
+text editor.  The output-formatting capabilities of C<perlcritic> are
+specifically intended for use with the "grep" or "compile" modes
+available in editors like C<emacs> and C<vim>.  In these modes, you
+can run an arbitrary command and the editor will parse the output into
+an interactive buffer that you can click on and jump to the relevant
+line of code.
 
 The Perl::Critic team thanks everyone who has helped integrate Perl-Critic
 with their favorite editor.  Your contributions in particular have made
 Perl-Critic a convenient and user-friendly tool for Perl developers of all
 stripes.  We sincerely appreciate your hard work.
 
+
 =head2 EMACS
 
-Joshua ben Jore has authored a minor-mode for emacs that allows you to run
-perlcritic on the current region or buffer.  You can run it on demand, or
-configure it to run automatically when you save the buffer.  The output
-appears in a hot-linked compiler buffer.  The code and installation
-instructions can be found in the F<extras> directory inside this distribution.
+Joshua ben Jore has authored a minor-mode for emacs that allows you to
+run perlcritic on the current region or buffer.  You can run it on
+demand, or configure it to run automatically when you save the buffer.
+The output appears in a hot-linked compiler buffer.  The code and
+installation instructions can be found in the F<extras> directory
+inside this distribution.
+
 
 =head2 VIM
 
 Scott Peshak has published F<perlchecker.vim>, which is available at
 L<http://www.vim.org/scripts/script.php?script_id=1731>.
 
+
 =head2 gVIM
 
-Fritz Mehner recently added support for C<perlcritic> to his fantastic gVIM
-plugin.  In addition to providing a very Perlish IDE, Fritz's plugin enables
-one-click access to C<perlcritic> and many other very useful utilities.  And
-all is seamlessly integrated into the editor. See
-L<http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for complete details.
+Fritz Mehner recently added support for C<perlcritic> to his fantastic
+gVIM plugin.  In addition to providing a very Perlish IDE, Fritz's
+plugin enables one-click access to C<perlcritic> and many other very
+useful utilities.  And all is seamlessly integrated into the editor.
+See L<http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
+complete details.
+
 
 =head2 EPIC
 
-EPIC is an open source Perl IDE based on the Eclipse platform.  Features
-supported are syntax highlighting, on-the-fly syntax check, content assist,
-perldoc support, source formatter, templating support and a Perl debugger.  Go
-to L<http://e-p-i-c.sourceforge.net> for more information about EPIC.
+EPIC is an open source Perl IDE based on the Eclipse platform.
+Features supported are syntax highlighting, on-the-fly syntax check,
+content assist, perldoc support, source formatter, templating support
+and a Perl debugger.  Go to L<http://e-p-i-c.sourceforge.net> for more
+information about EPIC.
+
+The EPIC team is currently working on integration with Perl::Critic.
+In the meantime, you can use the L<criticism|criticism> pragma and
+EPIC will highlight violations whenever it does a syntax check on your
+code.  I haven't tried this myself, but other folks say it works.
 
-The EPIC team is currently working on integration with Perl::Critic.  In the
-meantime, you can use the L<criticism> pragma and EPIC will highlight
-violations whenever it does a syntax check on your code.  I haven't tried this
-myself, but other folks say it works.
 
 =head2 BBEdit
 
-Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. A copy is
-included in this distribution at F<extras/perl_critic_for_bbedit-1_0.zip>. See
-L<http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml> for
-screenshots and additional installation info.  Apple users rejoice!
+Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. A
+copy is included in this distribution at
+F<extras/perl_critic_for_bbedit-1_0.zip>. See
+L<http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml>
+for screenshots and additional installation info.  Apple users
+rejoice!
+
 
 =head2 Komodo
 
-Komodo is a proprietary IDE for Perl and several other dynamic languages.
-Free trial copies of Komodo can be obtained from the ActiveState website at
-L<http://www.activestate.com>. For instructions on integrating F<perlcritic>
-with Komodo, see F<extras/KomodoIntegration.pod> in this distribution.
+Komodo is a proprietary IDE for Perl and several other dynamic
+languages.  Free trial copies of Komodo can be obtained from the
+ActiveState website at L<http://www.activestate.com>. For instructions
+on integrating F<perlcritic> with Komodo, see
+F<extras/KomodoIntegration.pod> in this distribution.
+
 
 =head1 EXIT STATUS
 
-If C<perlcritic> has any errors itself, exits with status == 1.  If there are
-no errors, but C<perlcritic> finds Policy violations in your source code,
-exits with status == 2.  If there were no errors and no violations were found,
-exits with status == 0.
+If C<perlcritic> has any errors itself, exits with status == 1.  If
+there are no errors, but C<perlcritic> finds Policy violations in your
+source code, exits with status == 2.  If there were no errors and no
+violations were found, exits with status == 0.
+
 
-=head1 THE L<Perl::Critic> PHILOSOPHY
+=head1 THE L<Perl::Critic|Perl::Critic> PHILOSOPHY
 
 =over
 
-Coding standards are deeply personal and highly subjective.  The goal of
-Perl::Critic is to help you write code that conforms with a set of best
-practices.  Our primary goal is not to dictate what those practices are, but
-rather, to implement the practices discovered by others.  Ultimately, you make
-the rules -- Perl::Critic is merely a tool for encouraging consistency.  If
-there is a policy that you think is important or that we have overlooked, we
-would be very grateful for contributions, or you can simply load your own
-private set of policies into Perl::Critic.
+Coding standards are deeply personal and highly subjective.  The goal
+of Perl::Critic is to help you write code that conforms with a set of
+best practices.  Our primary goal is not to dictate what those
+practices are, but rather, to implement the practices discovered by
+others.  Ultimately, you make the rules -- Perl::Critic is merely a
+tool for encouraging consistency.  If there is a policy that you think
+is important or that we have overlooked, we would be very grateful for
+contributions, or you can simply load your own private set of policies
+into Perl::Critic.
 
 =back
 
+
 =head1 EXTENDING THE CRITIC
 
-The modular design of Perl::Critic is intended to facilitate the addition of
-new Policies.  You'll need to have some understanding of L<PPI>, but most
-Policy modules are pretty straightforward and only require about 20 lines of
-code, and half of those lines are simple use statements and simple
-declarations..  Please see the L<Perl::Critic::DEVELOPER> file included in
-this distribution for a step-by-step demonstration of how to create new Policy
-modules.
-
-If you develop any new Policy modules, feel free to send them to
-C<< <thaljef@cpan.org> >> and I'll be happy to put them into the Perl::Critic
-distribution.  Or if you would like to work on the Perl::Critic project
-directly, check out our repository at L<http://perlcritic.tigris.org>.  To
-subscribe to our mailing list, send a message to
-C<< <dev-subscribe@perlcritic.tigris.org> >>.
-
-The Perl::Critic team is also available for hire.  If your organization has
-its own coding standards, we can create custom Policies to enforce your local
-guidelines.  Or if your code base is prone to a particular defect pattern, we
-can design Policies that will help you catch those costly defects B<before>
-they go into production.  To discuss your needs with the Perl::Critic team,
-just contact C<< <thaljef@cpan.org> >>.
+The modular design of Perl::Critic is intended to facilitate the
+addition of new Policies.  You'll need to have some understanding of
+L<PPI|PPI>, but most Policy modules are pretty straightforward and
+only require about 20 lines of code, and half of those lines are
+simple use statements and simple declarations..  Please see the
+L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> file included in
+this distribution for a step-by-step demonstration of how to create
+new Policy modules.
+
+If you develop any new Policy modules, feel free to send them to C<<
+<thaljef@cpan.org> >> and I'll be happy to put them into the
+Perl::Critic distribution.  Or if you would like to work on the
+Perl::Critic project directly, check out our repository at
+L<http://perlcritic.tigris.org>.  To subscribe to our mailing list,
+send a message to C<< <dev-subscribe@perlcritic.tigris.org> >>.
+
+The Perl::Critic team is also available for hire.  If your
+organization has its own coding standards, we can create custom
+Policies to enforce your local guidelines.  Or if your code base is
+prone to a particular defect pattern, we can design Policies that will
+help you catch those costly defects B<before> they go into production.
+To discuss your needs with the Perl::Critic team, just contact C<<
+<thaljef@cpan.org> >>.
+
 
 =head1 CONTACTING THE DEVELOPMENT TEAM
 
@@ -1311,44 +1371,48 @@ C<< <users-subscribe@perlcritic.tigris.org> >>.  See also
 L<the archives|http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
 You can also contact the author at C<< <thaljef@cpan.org> >>.
 
-At least one member of the development team has started hanging around in
-L<irc://irc.perl.org/#perlcritic>.
+At least one member of the development team has started hanging around
+in L<irc://irc.perl.org/#perlcritic>.
+
 
 =head1 SEE ALSO
 
-There are a number of distributions of additional Policies available.  A few
-are listed here:
+There are a number of distributions of additional Policies available.
+A few are listed here:
 
-L<Perl::Critic::More>
-L<Perl::Critic::Bangs>
-L<Perl::Critic::Lax>
-L<Perl::Critic::StricterSubs>
-L<Perl::Critic::Swift>
+L<Perl::Critic::More|Perl::Critic::More>
+L<Perl::Critic::Bangs|Perl::Critic::Bangs>
+L<Perl::Critic::Lax|Perl::Critic::Lax>
+L<Perl::Critic::StricterSubs|Perl::Critic::StricterSubs>
+L<Perl::Critic::Swift|Perl::Critic::Swift>
 
 These distributions enable you to use Perl::Critic in your unit tests:
 
-L<Test::Perl::Critic>
-L<Test::Perl::Critic::Progressive>
+L<Test::Perl::Critic|Test::Perl::Critic>
+L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive>
 
 There are also a couple of distributions that will install all the
 Perl::Critic related modules known to the development team:
 
-L<Bundle::Perl::Critic>
-L<Task::Perl::Critic>
+L<Bundle::Perl::Critic|Bundle::Perl::Critic>
+L<Task::Perl::Critic|Task::Perl::Critic>
+
 
 =head1 BUGS
 
-Scrutinizing Perl code is hard for humans, let alone machines.  If you find
-any bugs, particularly false-positives or false-negatives from a
+Scrutinizing Perl code is hard for humans, let alone machines.  If you
+find any bugs, particularly false-positives or false-negatives from a
 Perl::Critic::Policy, please submit them to
 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.  Thanks.
 
 Most policies will produce false-negatives if they cannot understand a
 particular block of code.
 
+
 =head1 CREDITS
 
-Adam Kennedy - For creating L<PPI>, the heart and soul of L<Perl::Critic>.
+Adam Kennedy - For creating L<PPI|PPI>, the heart and soul of
+L<Perl::Critic|Perl::Critic>.
 
 Damian Conway - For writing B<Perl Best Practices>, finally :)
 
@@ -1362,17 +1426,19 @@ Giuseppe Maxia - For all the great ideas and positive encouragement.
 
 and Sharon, my wife - For putting up with my all-night code sessions.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 
-This program is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself.  The full text of this license can be found in
-the LICENSE file included with this module.
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.  The full text of this license
+can be found in the LICENSE file included with this module.
 
 =cut
 
index 1ea21f6..1eaf890 100644 (file)
@@ -18,8 +18,8 @@ string, in which case the string is used as the parameter name, or
 around the new hash reference specifications.
 
 The absence of a requirement for a Policy's constructor to call the
-base L<Perl::Critic::Policy> constructor did cause problems that had
-to be worked around.
+base L<Perl::Critic::Policy|Perl::Critic::Policy> constructor did
+cause problems that had to be worked around.
 
 =item Must not require configuration items to be parsed multiple times.
 
@@ -139,8 +139,7 @@ without breaking anything.
 
 Rather than using I<is a> relationships, C<PolicyParameter> objects
 I<have a> C<Behavior>.  This means that a developer can use the base
-functionality of a C<Behavior>, but override the parts that they
-want.
+functionality of a C<Behavior>, but override the parts that they want.
 
 =back
 
index 4c864de..230411c 100755 (executable)
@@ -209,15 +209,15 @@ C<generatestats> - Produce some simple quality statistics of a codebase
 
 =head1 USAGE
 
-  generatestats path [...]
+    generatestats path [...]
 
 
 =head1 DESCRIPTION
 
 Scan a body of code and generate some statistics on violations of the
-installed L<Perl::Critic> policies.  While there is no means of configuring
-the policies here, this will take into account your F<.perlcriticrc>, if
-available.
+installed L<Perl::Critic|Perl::Critic> policies.  While there is no means of
+configuring the policies here, this will take into account your
+F<.perlcriticrc>, if available.
 
 
 =head1 REQUIRED ARGUMENTS
@@ -247,9 +247,9 @@ None.
 
 =head1 DEPENDENCIES
 
-L<Perl::Critic>
-L<Perl6::Say>
-L<Readonly>
+L<Perl::Critic|Perl::Critic>
+L<Perl6::Say|Perl6::Say>
+L<Readonly|Readonly>
 
 
 =head1 INCOMPATIBILITIES
@@ -273,7 +273,7 @@ Copyright (c) 2006-2007, Elliot Shank C<< <perl@galumph.com> >>. All rights
 reserved.
 
 This module is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself. See L<perlartistic>.
+the same terms as Perl itself. See L<perlartistic|perlartistic>.
 
 
 =head1 DISCLAIMER OF WARRANTY
index e49affc..d0001ce 100755 (executable)
@@ -227,23 +227,25 @@ C<loadanalysisdb> - Critique a body of code and load the results into a database
 
 =head1 USAGE
 
-  loadanalysisdb path [...]
+    loadanalysisdb path [...]
 
 
 =head1 DESCRIPTION
 
-Scan a body of code and, rather than emit the results in a textual format, put
-them into a database so that analyses can be made.
+Scan a body of code and, rather than emit the results in a textual
+format, put them into a database so that analyses can be made.
 
-This example doesn't put anything into the database that isn't available from
-L<Perl::Critic::Violation> in order to keep the code easier to understand.  In
-a full application of the idea presented here, one might want to include the
-current date and a distribution name in the database so that progress on
-cleaning up a code corpus can be tracked.
+This example doesn't put anything into the database that isn't
+available from L<Perl::Critic::Violation|Perl::Critic::Violation> in
+order to keep the code easier to understand.  In a full application of
+the idea presented here, one might want to include the current date
+and a distribution name in the database so that progress on cleaning
+up a code corpus can be tracked.
 
-Note the explanation attribute of L<Perl::Critic::Violation> is constant for
-most policies, but some of them do provide more specific diagnostics of the
-code in question.
+Note the explanation attribute of
+L<Perl::Critic::Violation|Perl::Critic::Violation> is constant for
+most policies, but some of them do provide more specific diagnostics
+of the code in question.
 
 
 =head1 REQUIRED ARGUMENTS
@@ -258,7 +260,7 @@ None.
 
 =head1 DIAGNOSTICS
 
-Errors from L<DBI>.
+Errors from L<DBI|DBI>.
 
 
 =head1 EXIT STATUS
@@ -273,13 +275,13 @@ None.
 
 =head1 DEPENDENCIES
 
-L<Perl::Critic>
-L<DBD::SQLite>
-L<Perl6::Say>
-L<Readonly>
+L<Perl::Critic|Perl::Critic>
+L<DBD::SQLite|DBD::SQLite>
+L<Perl6::Say|Perl6::Say>
+L<Readonly|Readonly>
 
-An SQLite database named "perl_critic_analysis.sqlite" with the following
-schema:
+An SQLite database named "perl_critic_analysis.sqlite" with the
+following schema:
 
   CREATE TABLE violation (
       file_path     VARCHAR(1024),
@@ -309,33 +311,35 @@ Elliot Shank  C<< <perl@galumph.com> >>
 
 =head1 COPYRIGHT
 
-Copyright (c) 2006-2007, Elliot Shank C<< <perl@galumph.com> >>. All rights
-reserved.
+Copyright (c) 2006-2007, Elliot Shank C<< <perl@galumph.com> >>. All
+rights reserved.
 
-This module is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself. See L<perlartistic>.
+This module is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself. See L<perlartistic|perlartistic>.
 
 
 =head1 DISCLAIMER OF WARRANTY
 
-BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
-SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
-STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
-SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE,
-YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
-
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
-COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
-SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO
-LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
-THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER
-SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
+BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
+WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
+PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
+EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE
+TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
 
 =cut
 
index 08011e3..70cdd2d 100644 (file)
@@ -186,8 +186,9 @@ about what it is doing.
 =item C<dump_unlisted_or_optional_module_versions()>
 
 Prints to C<STDOUT> a list of all the unlisted (e.g. things in core
-like L<Exporter>), optional (e.g. L<File::Which>), or potentially
-indirect (e.g. L<Readonly::XS>) dependencies, plus their versions, if
+like L<Exporter|Exporter>), optional (e.g.
+L<File::Which|File::Which>), or potentially indirect (e.g.
+L<Readonly::XS|Readonly::XS>) dependencies, plus their versions, if
 they're installed.
 
 
index 9dc5a89..23c383b 100644 (file)
@@ -420,39 +420,43 @@ Perl::Critic - Critique Perl source code for best-practices.
 
 =head1 DESCRIPTION
 
-Perl::Critic is an extensible framework for creating and applying coding
-standards to Perl source code.  Essentially, it is a static source code
-analysis engine.  Perl::Critic is distributed with a number of
-L<Perl::Critic::Policy> modules that attempt to enforce various coding
-guidelines.  Most Policy modules are based on Damian Conway's book B<Perl Best
-Practices>.  However, Perl::Critic is B<not> limited to PBP and will even
-support Policies that contradict Conway.  You can enable, disable, and
-customize those Polices through the Perl::Critic interface.  You can also
-create new Policy modules that suit your own tastes.
-
-For a command-line interface to Perl::Critic, see the documentation for
-L<perlcritic>.  If you want to integrate Perl::Critic with your build process,
-L<Test::Perl::Critic> provides an interface that is suitable for test scripts.
-Also, L<Test::Perl::Critic::Progressive> is useful for gradually applying
-coding standards to legacy code.  For the ultimate convenience (at the expense
-of some flexibility) see the L<criticism> pragma.
-
-Win32 and ActivePerl users can find PPM distributions of Perl::Critic at
-L<http://theoryx5.uwinnipeg.ca/ppms/>.
-
-If you'd like to try L<Perl::Critic> without installing anything, there is a
-web-service available at L<http://perlcritic.com>.  The web-service does not
-yet support all the configuration features that are available in the native
-Perl::Critic API, but it should give you a good idea of what it does.  You can
-also invoke the perlcritic web-service from the command-line by doing an
-HTTP-post, such as one of these:
+Perl::Critic is an extensible framework for creating and applying
+coding standards to Perl source code.  Essentially, it is a static
+source code analysis engine.  Perl::Critic is distributed with a
+number of L<Perl::Critic::Policy|Perl::Critic::Policy> modules that
+attempt to enforce various coding guidelines.  Most Policy modules are
+based on Damian Conway's book B<Perl Best Practices>.  However,
+Perl::Critic is B<not> limited to PBP and will even support Policies
+that contradict Conway.  You can enable, disable, and customize those
+Polices through the Perl::Critic interface.  You can also create new
+Policy modules that suit your own tastes.
+
+For a command-line interface to Perl::Critic, see the documentation
+for L<perlcritic|perlcritic>.  If you want to integrate Perl::Critic
+with your build process, L<Test::Perl::Critic|Test::Perl::Critic>
+provides an interface that is suitable for test scripts.  Also,
+L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive> is
+useful for gradually applying coding standards to legacy code.  For
+the ultimate convenience (at the expense of some flexibility) see the
+L<criticism|criticism> pragma.
+
+Win32 and ActivePerl users can find PPM distributions of Perl::Critic
+at L<http://theoryx5.uwinnipeg.ca/ppms/>.
+
+If you'd like to try L<Perl::Critic|Perl::Critic> without installing
+anything, there is a web-service available at
+L<http://perlcritic.com>.  The web-service does not yet support all
+the configuration features that are available in the native
+Perl::Critic API, but it should give you a good idea of what it does.
+You can also invoke the perlcritic web-service from the command-line
+by doing an HTTP-post, such as one of these:
 
    $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
    $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
    $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
 
-Please note that the perlcritic web-service is still alpha code.  The URL and
-interface to the service are subject to change.
+Please note that the perlcritic web-service is still alpha code.  The
+URL and interface to the service are subject to change.
 
 
 =head1 CONSTRUCTOR
@@ -465,31 +469,35 @@ interface to the service are subject to change.
 
 =item C<< new() >>
 
-Returns a reference to a new Perl::Critic object.  Most arguments are just
-passed directly into L<Perl::Critic::Config>, but I have described them here
-as well.  The default value for all arguments can be defined in your
-F<.perlcriticrc> file.  See the L<"CONFIGURATION"> section for more
-information about that.  All arguments are optional key-value pairs as
-follows:
-
-B<-profile> is a path to a configuration file. If C<$FILE> is not defined,
-Perl::Critic::Config attempts to find a F<.perlcriticrc> configuration file in
-the current directory, and then in your home directory.  Alternatively, you
-can set the C<PERLCRITIC> environment variable to point to a file in another
-location.  If a configuration file can't be found, or if C<$FILE> is an empty
-string, then all Policies will be loaded with their default configuration.
-See L<"CONFIGURATION"> for more information.
-
-B<-severity> is the minimum severity level.  Only Policy modules that have a
-severity greater than C<$N> will be applied.  Severity values are integers
-ranging from 1 (least severe) to 5 (most severe).  The default is 5.  For a
-given C<-profile>, decreasing the C<-severity> will usually reveal more Policy
-violations.  You can set the default value for this option in your
-F<.perlcriticrc> file.  Users can redefine the severity level for any Policy
-in their F<.perlcriticrc> file.  See L<"CONFIGURATION"> for more information.
-
-If it is difficult for you to remember whether severity "5" is the most or
-least restrictive level, then you can use one of these named values:
+Returns a reference to a new Perl::Critic object.  Most arguments are
+just passed directly into
+L<Perl::Critic::Config|Perl::Critic::Config>, but I have described
+them here as well.  The default value for all arguments can be defined
+in your F<.perlcriticrc> file.  See the L<"CONFIGURATION"> section for
+more information about that.  All arguments are optional key-value
+pairs as follows:
+
+B<-profile> is a path to a configuration file. If C<$FILE> is not
+defined, Perl::Critic::Config attempts to find a F<.perlcriticrc>
+configuration file in the current directory, and then in your home
+directory.  Alternatively, you can set the C<PERLCRITIC> environment
+variable to point to a file in another location.  If a configuration
+file can't be found, or if C<$FILE> is an empty string, then all
+Policies will be loaded with their default configuration.  See
+L<"CONFIGURATION"> for more information.
+
+B<-severity> is the minimum severity level.  Only Policy modules that
+have a severity greater than C<$N> will be applied.  Severity values
+are integers ranging from 1 (least severe) to 5 (most severe).  The
+default is 5.  For a given C<-profile>, decreasing the C<-severity>
+will usually reveal more Policy violations.  You can set the default
+value for this option in your F<.perlcriticrc> file.  Users can
+redefine the severity level for any Policy in their F<.perlcriticrc>
+file.  See L<"CONFIGURATION"> for more information.
+
+If it is difficult for you to remember whether severity "5" is the
+most or least restrictive level, then you can use one of these named
+values:
 
     SEVERITY NAME   ...is equivalent to...   SEVERITY NUMBER
     --------------------------------------------------------
@@ -499,61 +507,63 @@ least restrictive level, then you can use one of these named values:
     -severity => 'cruel'                      -severity => 2
     -severity => 'brutal'                     -severity => 1
 
-B<-theme> is special expression that determines which Policies to apply based
-on their respective themes.  For example, the following would load only
-Policies that have a 'bugs' AND 'pbp' theme:
+B<-theme> is special expression that determines which Policies to
+apply based on their respective themes.  For example, the following
+would load only Policies that have a 'bugs' AND 'pbp' theme:
 
   my $critic = Perl::Critic->new( -theme => 'bugs && pbp' );
 
-Unless the C<-severity> option is explicitly given, setting C<-theme> silently
-causes the C<-severity> to be set to 1.  You can set the default value for
-this option in your F<.perlcriticrc> file.  See the L<"POLICY THEMES"> section
-for more information about themes.
+Unless the C<-severity> option is explicitly given, setting C<-theme>
+silently causes the C<-severity> to be set to 1.  You can set the
+default value for this option in your F<.perlcriticrc> file.  See the
+L<"POLICY THEMES"> section for more information about themes.
 
 
-B<-include> is a reference to a list of string C<@PATTERNS>.  Policy modules
-that match at least one C<m/$PATTERN/imx> will always be loaded, irrespective
-of all other settings.  For example:
+B<-include> is a reference to a list of string C<@PATTERNS>.  Policy
+modules that match at least one C<m/$PATTERN/imx> will always be
+loaded, irrespective of all other settings.  For example:
 
   my $critic = Perl::Critic->new(-include => ['layout'] -severity => 4);
 
-This would cause Perl::Critic to apply all the C<CodeLayout::*> Policy modules
-even though they have a severity level that is less than 4.  You can set the
-default value for this option in your F<.perlcriticrc> file.  You can also use
-C<-include> in conjunction with the C<-exclude> option.  Note that C<-exclude>
-takes precedence over C<-include> when a Policy matches both patterns.
+This would cause Perl::Critic to apply all the C<CodeLayout::*> Policy
+modules even though they have a severity level that is less than 4.
+You can set the default value for this option in your F<.perlcriticrc>
+file.  You can also use C<-include> in conjunction with the
+C<-exclude> option.  Note that C<-exclude> takes precedence over
+C<-include> when a Policy matches both patterns.
 
-B<-exclude> is a reference to a list of string C<@PATTERNS>.  Policy modules
-that match at least one C<m/$PATTERN/imx> will not be loaded, irrespective of
-all other settings.  For example:
+B<-exclude> is a reference to a list of string C<@PATTERNS>.  Policy
+modules that match at least one C<m/$PATTERN/imx> will not be loaded,
+irrespective of all other settings.  For example:
 
   my $critic = Perl::Critic->new(-exclude => ['strict'] -severity => 1);
 
 This would cause Perl::Critic to not apply the C<RequireUseStrict> and
-C<ProhibitNoStrict> Policy modules even though they have a severity level that
-is greater than 1.  You can set the default value for this option in your
-F<.perlcriticrc> file.  You can also use C<-exclude> in conjunction with the
-C<-include> option.  Note that C<-exclude> takes precedence over C<-include>
-when a Policy matches both patterns.
-
-B<-single-policy> is a string C<PATTERN>.  Only one policy that matches
-C<m/$PATTERN/imx> will be used.  Policies that do not match will be excluded.
-This option has precedence over the C<-severity>, C<-theme>, C<-include>,
-C<-exclude>, and C<-only> options.  You can set the default value for this
-option in your F<.perlcriticrc> file.
-
-B<-top> is the maximum number of Violations to return when ranked by their
-severity levels.  This must be a positive integer.  Violations are still
-returned in the order that they occur within the file.  Unless the
-C<-severity> option is explicitly given, setting C<-top> silently causes the
-C<-severity> to be set to 1.  You can set the default value for this option in
-your F<.perlcriticrc> file.
-
-B<-only> is a boolean value.  If set to a true value, Perl::Critic will only
-choose from Policies that are mentioned in the user's profile.  If set to a
-false value (which is the default), then Perl::Critic chooses from all the
-Policies that it finds at your site.  You can set the default value for this
-option in your F<.perlcriticrc> file.
+C<ProhibitNoStrict> Policy modules even though they have a severity
+level that is greater than 1.  You can set the default value for this
+option in your F<.perlcriticrc> file.  You can also use C<-exclude> in
+conjunction with the C<-include> option.  Note that C<-exclude> takes
+precedence over C<-include> when a Policy matches both patterns.
+
+B<-single-policy> is a string C<PATTERN>.  Only one policy that
+matches C<m/$PATTERN/imx> will be used.  Policies that do not match
+will be excluded.  This option has precedence over the C<-severity>,
+C<-theme>, C<-include>, C<-exclude>, and C<-only> options.  You can
+set the default value for this option in your F<.perlcriticrc> file.
+
+B<-top> is the maximum number of Violations to return when ranked by
+their severity levels.  This must be a positive integer.  Violations
+are still returned in the order that they occur within the file.
+Unless the C<-severity> option is explicitly given, setting C<-top>
+silently causes the C<-severity> to be set to 1.  You can set the
+default value for this option in your F<.perlcriticrc> file.
+
+B<-only> is a boolean value.  If set to a true value, Perl::Critic
+will only choose from Policies that are mentioned in the user's
+profile.  If set to a false value (which is the default), then
+Perl::Critic chooses from all the Policies that it finds at your site.
+You can set the default value for this option in your F<.perlcriticrc>
+file.
 
 B<-profile-strictness> is an enumerated value, one of
 L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_WARN"> (the
@@ -569,28 +579,31 @@ situation fatal.  Correspondingly,
 L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_QUIET"> makes
 Perl::Critic shut up about these things.
 
-B<-force> is a boolean value that controls whether Perl::Critic observes the
-magical C<"## no critic"> pseudo-pragmas in your code.  If set to a true
-value, Perl::Critic will analyze all code.  If set to a false value (which is
-the default) Perl::Critic will ignore code that is tagged with these comments.
-See L<"BENDING THE RULES"> for more information.  You can set the default
-value for this option in your F<.perlcriticrc> file.
+B<-force> is a boolean value that controls whether Perl::Critic
+observes the magical C<"## no critic"> pseudo-pragmas in your code.
+If set to a true value, Perl::Critic will analyze all code.  If set to
+a false value (which is the default) Perl::Critic will ignore code
+that is tagged with these comments.  See L<"BENDING THE RULES"> for
+more information.  You can set the default value for this option in
+your F<.perlcriticrc> file.
 
-B<-verbose> can be a positive integer (from 1 to 11), or a literal format
-specification.  See L<Perl::Critic::Violation> for an explanation of format
-specifications.  You can set the default value for this option in your
-F<.perlcriticrc> file.
+B<-verbose> can be a positive integer (from 1 to 11), or a literal
+format specification.  See
+L<Perl::Critic::Violation|Perl::Critic::Violation> for an explanation
+of format specifications.  You can set the default value for this
+option in your F<.perlcriticrc> file.
 
-B<-color> is not used by Perl::Critic but is provided for the benefit of
-L<perlcritic>.
+B<-color> is not used by Perl::Critic but is provided for the benefit
+of L<perlcritic|perlcritic>.
 
-B<-criticism-fatal> is not used by Perl::Critic but is provided for the
-benefit of L<criticism>.
+B<-criticism-fatal> is not used by Perl::Critic but is provided for
+the benefit of L<criticism|criticism>.
 
-B<-config> is a reference to a L<Perl::Critic::Config> object.  If you have
-created your own Config object for some reason, you can pass it in here
-instead of having Perl::Critic create one for you.  Using the C<-config>
-option causes all the other options to be silently ignored.
+B<-config> is a reference to a
+L<Perl::Critic::Config|Perl::Critic::Config> object.  If you have
+created your own Config object for some reason, you can pass it in
+here instead of having Perl::Critic create one for you.  Using the
+C<-config> option causes all the other options to be silently ignored.
 
 =back
 
@@ -602,56 +615,61 @@ option causes all the other options to be silently ignored.
 =item C<critique( $source_code )>
 
 Runs the C<$source_code> through the Perl::Critic engine using all the
-Policies that have been loaded into this engine.  If C<$source_code> is a
-scalar reference, then it is treated as a string of actual Perl code.  If
-C<$source_code> is a reference to an instance of L<PPI::Document>, then that
-instance is used directly.  Otherwise, it is treated as a path to a local file
-containing Perl code.  This method returns a list of
-L<Perl::Critic::Violation> objects for each violation of the loaded Policies.
-The list is sorted in the order that the Violations appear in the code.  If
-there are no violations, this method returns an empty list.
+Policies that have been loaded into this engine.  If C<$source_code>
+is a scalar reference, then it is treated as a string of actual Perl
+code.  If C<$source_code> is a reference to an instance of
+L<PPI::Document|PPI::Document>, then that instance is used directly.
+Otherwise, it is treated as a path to a local file containing Perl
+code.  This method returns a list of
+L<Perl::Critic::Violation|Perl::Critic::Violation> objects for each
+violation of the loaded Policies.  The list is sorted in the order
+that the Violations appear in the code.  If there are no violations,
+this method returns an empty list.
 
 =item C<< add_policy( -policy => $policy_name, -params => \%param_hash ) >>
 
-Creates a Policy object and loads it into this Critic.  If the object cannot
-be instantiated, it will throw a fatal exception.  Otherwise, it returns a
-reference to this Critic.
+Creates a Policy object and loads it into this Critic.  If the object
+cannot be instantiated, it will throw a fatal exception.  Otherwise,
+it returns a reference to this Critic.
 
-B<-policy> is the name of a L<Perl::Critic::Policy> subclass module.  The
-C<'Perl::Critic::Policy'> portion of the name can be omitted for brevity.
-This argument is required.
+B<-policy> is the name of a
+L<Perl::Critic::Policy|Perl::Critic::Policy> subclass module.  The
+C<'Perl::Critic::Policy'> portion of the name can be omitted for
+brevity.  This argument is required.
 
-B<-params> is an optional reference to a hash of Policy parameters.  The
-contents of this hash reference will be passed into to the constructor of the
-Policy module.  See the documentation in the relevant Policy module for a
-description of the arguments it supports.
+B<-params> is an optional reference to a hash of Policy parameters.
+The contents of this hash reference will be passed into to the
+constructor of the Policy module.  See the documentation in the
+relevant Policy module for a description of the arguments it supports.
 
 =item C< policies() >
 
-Returns a list containing references to all the Policy objects that have been
-loaded into this engine.  Objects will be in the order that they were loaded.
+Returns a list containing references to all the Policy objects that
+have been loaded into this engine.  Objects will be in the order that
+they were loaded.
 
 =item C< config() >
 
-Returns the L<Perl::Critic::Config> object that was created for or given
-to this Critic.
+Returns the L<Perl::Critic::Config|Perl::Critic::Config> object that
+was created for or given to this Critic.
 
 =item C< statistics() >
 
-Returns the L<Perl::Critic::Statistics> object that was created for this
-Critic.  The Statistics object accumulates data for all files that are
-analyzed by this Critic.
+Returns the L<Perl::Critic::Statistics|Perl::Critic::Statistics>
+object that was created for this Critic.  The Statistics object
+accumulates data for all files that are analyzed by this Critic.
 
 =back
 
 
 =head1 FUNCTIONAL INTERFACE
 
-For those folks who prefer to have a functional interface, The C<critique>
-method can be exported on request and called as a static function.  If the
-first argument is a hashref, its contents are used to construct a new
-Perl::Critic object internally.  The keys of that hash should be the same as
-those supported by the C<Perl::Critic::new> method.  Here are some examples:
+For those folks who prefer to have a functional interface, The
+C<critique> method can be exported on request and called as a static
+function.  If the first argument is a hashref, its contents are used
+to construct a new Perl::Critic object internally.  The keys of that
+hash should be the same as those supported by the C<Perl::Critic::new>
+method.  Here are some examples:
 
   use Perl::Critic qw(critique);
 
@@ -670,24 +688,26 @@ functions.  Sorry.
 
 =head1 CONFIGURATION
 
-Most of the settings for Perl::Critic and each of the Policy modules can be
-controlled by a configuration file.  The default configuration file is called
-F<.perlcriticrc>.  Perl::Critic will look for this file in the current
-directory first, and then in your home directory.  Alternatively, you can set
-the C<PERLCRITIC> environment variable to explicitly point to a different file
-in another location.  If none of these files exist, and the C<-profile> option
-is not given to the constructor, then all the modules that are found in the
+Most of the settings for Perl::Critic and each of the Policy modules
+can be controlled by a configuration file.  The default configuration
+file is called F<.perlcriticrc>.  Perl::Critic will look for this file
+in the current directory first, and then in your home directory.
+Alternatively, you can set the C<PERLCRITIC> environment variable to
+explicitly point to a different file in another location.  If none of
+these files exist, and the C<-profile> option is not given to the
+constructor, then all the modules that are found in the
 Perl::Critic::Policy namespace will be loaded with their default
 configuration.
 
-The format of the configuration file is a series of INI-style blocks that
-contain key-value pairs separated by '='. Comments should start with '#' and
-can be placed on a separate line or after the name-value pairs if you desire.
+The format of the configuration file is a series of INI-style blocks
+that contain key-value pairs separated by '='. Comments should start
+with '#' and can be placed on a separate line or after the name-value
+pairs if you desire.
 
-Default settings for Perl::Critic itself can be set B<before the first named
-block.> For example, putting any or all of these at the top of your
-configuration file will set the default value for the corresponding
-constructor argument.
+Default settings for Perl::Critic itself can be set B<before the first
+named block.> For example, putting any or all of these at the top of
+your configuration file will set the default value for the
+corresponding constructor argument.
 
     severity  = 3                                     #Integer or named level
     only      = 1                                     #Zero or One
@@ -700,7 +720,8 @@ constructor argument.
     criticism-fatal = 1                               #Zero or One
     color     = 1                                     #Zero or One
 
-The remainder of the configuration file is a series of blocks like this:
+The remainder of the configuration file is a series of blocks like
+this:
 
     [Perl::Critic::Policy::Category::PolicyName]
     severity = 1
@@ -710,18 +731,20 @@ The remainder of the configuration file is a series of blocks like this:
     arg1 = value1
     arg2 = value2
 
-C<Perl::Critic::Policy::Category::PolicyName> is the full name of a module
-that implements the policy.  The Policy modules distributed with Perl::Critic
-have been grouped into categories according to the table of contents in Damian
-Conway's book B<Perl Best Practices>. For brevity, you can omit the
-C<'Perl::Critic::Policy'> part of the module name.
-
-C<severity> is the level of importance you wish to assign to the Policy.  All
-Policy modules are defined with a default severity value ranging from 1 (least
-severe) to 5 (most severe).  However, you may disagree with the default
-severity and choose to give it a higher or lower severity, based on your own
-coding philosophy.  You can set the C<severity> to an integer from 1 to 5, or
-use one of the equivalent names:
+C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
+module that implements the policy.  The Policy modules distributed
+with Perl::Critic have been grouped into categories according to the
+table of contents in Damian Conway's book B<Perl Best Practices>. For
+brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
+name.
+
+C<severity> is the level of importance you wish to assign to the
+Policy.  All Policy modules are defined with a default severity value
+ranging from 1 (least severe) to 5 (most severe).  However, you may
+disagree with the default severity and choose to give it a higher or
+lower severity, based on your own coding philosophy.  You can set the
+C<severity> to an integer from 1 to 5, or use one of the equivalent
+names:
 
     SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
     ----------------------------------------------------
@@ -731,31 +754,33 @@ use one of the equivalent names:
     cruel                                              2
     brutal                                             1
 
-C<set_themes> sets the theme for the Policy and overrides its default theme.
-The argument is a string of one or more whitespace-delimited alphanumeric
-words.  Themes are case-insensitive.  See L<"POLICY THEMES"> for more
-information.
+C<set_themes> sets the theme for the Policy and overrides its default
+theme.  The argument is a string of one or more whitespace-delimited
+alphanumeric words.  Themes are case-insensitive.  See L<"POLICY
+THEMES"> for more information.
 
-C<add_themes> appends to the default themes for this Policy.  The argument is
-a string of one or more whitespace-delimited words.  Themes are
-case-insensitive.  See L<"POLICY THEMES"> for more information.
+C<add_themes> appends to the default themes for this Policy.  The
+argument is a string of one or more whitespace-delimited words.
+Themes are case-insensitive.  See L<"POLICY THEMES"> for more
+information.
 
-C<maximum_violations_per_document> limits the number of Violations the Policy
-will return for a given document.  Some Policies have a default limit; see the
-documentation for the individual Policies to see whether there is one.  To
-force a Policy to not have a limit, specify "no_limit" or the empty string for
-the value of this parameter.
+C<maximum_violations_per_document> limits the number of Violations the
+Policy will return for a given document.  Some Policies have a default
+limit; see the documentation for the individual Policies to see
+whether there is one.  To force a Policy to not have a limit, specify
+"no_limit" or the empty string for the value of this parameter.
 
-The remaining key-value pairs are configuration parameters that will be passed
-into the constructor for that Policy.  The constructors for most Policy
-objects do not support arguments, and those that do should have reasonable
-defaults.  See the documentation on the appropriate Policy module for more
-details.
+The remaining key-value pairs are configuration parameters that will
+be passed into the constructor for that Policy.  The constructors for
+most Policy objects do not support arguments, and those that do should
+have reasonable defaults.  See the documentation on the appropriate
+Policy module for more details.
 
-Instead of redefining the severity for a given Policy, you can completely
-disable a Policy by prepending a '-' to the name of the module in your
-configuration file.  In this manner, the Policy will never be loaded,
-regardless of the C<-severity> given to the Perl::Critic constructor.
+Instead of redefining the severity for a given Policy, you can
+completely disable a Policy by prepending a '-' to the name of the
+module in your configuration file.  In this manner, the Policy will
+never be loaded, regardless of the C<-severity> given to the
+Perl::Critic constructor.
 
 A simple configuration might look like this:
 
@@ -801,36 +826,38 @@ A simple configuration might look like this:
 For additional configuration examples, see the F<perlcriticrc> file
 that is included in this F<examples> directory of this distribution.
 
-Damian Conway's own Perl::Critic configuration is also included in this
-distribution as F<examples/perlcriticrc-conway>.
+Damian Conway's own Perl::Critic configuration is also included in
+this distribution as F<examples/perlcriticrc-conway>.
 
 
 =head1 THE POLICIES
 
-A large number of Policy modules are distributed with Perl::Critic.  They are
-described briefly in the companion document L<Perl::Critic::PolicySummary> and
-in more detail in the individual modules themselves.  Say C<"perlcritic -doc
-PATTERN"> to see the perldoc for all Policy modules that match the regex
-C<m/PATTERN/imx>
+A large number of Policy modules are distributed with Perl::Critic.
+They are described briefly in the companion document
+L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
+detail in the individual modules themselves.  Say C<"perlcritic -doc
+PATTERN"> to see the perldoc for all Policy modules that match the
+regex C<m/PATTERN/imx>
 
-There are a number of distributions of additional policies on CPAN.  If
-L<Perl::Critic> doesn't contain a policy that you want, some one may have
-already written it.  See the L</"SEE ALSO"> section below for a list of some
-of these distributions.
+There are a number of distributions of additional policies on CPAN.
+If L<Perl::Critic|Perl::Critic> doesn't contain a policy that you
+want, some one may have already written it.  See the L</"SEE ALSO">
+section below for a list of some of these distributions.
 
 
 =head1 POLICY THEMES
 
-Each Policy is defined with one or more "themes".  Themes can be used to
-create arbitrary groups of Policies.  They are intended to provide an
-alternative mechanism for selecting your preferred set of Policies.  For
-example, you may wish disable a certain subset of Policies when analyzing test
-scripts.  Conversely, you may wish to enable only a specific subset of
-Policies when analyzing modules.
+Each Policy is defined with one or more "themes".  Themes can be used
+to create arbitrary groups of Policies.  They are intended to provide
+an alternative mechanism for selecting your preferred set of Policies.
+For example, you may wish disable a certain subset of Policies when
+analyzing test scripts.  Conversely, you may wish to enable only a
+specific subset of Policies when analyzing modules.
 
 The Policies that ship with Perl::Critic are have been broken into the
-following themes.  This is just our attempt to provide some basic logical
-groupings.  You are free to invent new themes that suit your needs.
+following themes.  This is just our attempt to provide some basic
+logical groupings.  You are free to invent new themes that suit your
+needs.
 
     THEME             DESCRIPTION
     --------------------------------------------------------------------------
@@ -844,15 +871,16 @@ groupings.  You are free to invent new themes that suit your needs.
     tests             Policies that are specific to test scripts
 
 
-Any Policy may fit into multiple themes.  Say C<"perlcritic -list"> to get a
-listing of all available Policies and the themes that are associated with each
-one.  You can also change the theme for any Policy in your F<.perlcriticrc>
-file.  See the L<"CONFIGURATION"> section for more information about that.
+Any Policy may fit into multiple themes.  Say C<"perlcritic -list"> to
+get a listing of all available Policies and the themes that are
+associated with each one.  You can also change the theme for any
+Policy in your F<.perlcriticrc> file.  See the L<"CONFIGURATION">
+section for more information about that.
 
-Using the C<-theme> option, you can create an arbitrarily complex rule that
-determines which Policies will be loaded.  Precedence is the same as regular
-Perl code, and you can use parentheses to enforce precedence as well.
-Supported operators are:
+Using the C<-theme> option, you can create an arbitrarily complex rule
+that determines which Policies will be loaded.  Precedence is the same
+as regular Perl code, and you can use parentheses to enforce
+precedence as well.  Supported operators are:
 
    Operator    Altertative    Example
    ----------------------------------------------------------------------------
@@ -860,20 +888,20 @@ Supported operators are:
    ||          or             'pbp || (bugs && security)'
    !           not            'pbp && ! (portability || complexity)'
 
-Theme names are case-insensitive.  If the C<-theme> is set to an empty string,
-then it evaluates as true all Policies.
+Theme names are case-insensitive.  If the C<-theme> is set to an empty
+string, then it evaluates as true all Policies.
 
 
 =head1 BENDING THE RULES
 
-Perl::Critic takes a hard-line approach to your code: either you comply or you
-don't.  In the real world, it is not always practical (nor even possible) to
-fully comply with coding standards.  In such cases, it is wise to show that
-you are knowingly violating the standards and that you have a Damn Good Reason
-(DGR) for doing so.
+Perl::Critic takes a hard-line approach to your code: either you
+comply or you don't.  In the real world, it is not always practical
+(nor even possible) to fully comply with coding standards.  In such
+cases, it is wise to show that you are knowingly violating the
+standards and that you have a Damn Good Reason (DGR) for doing so.
 
-To help with those situations, you can direct Perl::Critic to ignore certain
-lines or blocks of code by using pseudo-pragmas:
+To help with those situations, you can direct Perl::Critic to ignore
+certain lines or blocks of code by using pseudo-pragmas:
 
     require 'LegacyLibaray1.pl';  ## no critic
     require 'LegacyLibrary2.pl';  ## no critic
@@ -892,19 +920,20 @@ lines or blocks of code by using pseudo-pragmas:
         do_something($_);
     }
 
-The C<"## no critic"> comments direct Perl::Critic to ignore the remaining
-lines of code until the end of the current block, or until a C<"## use
-critic"> comment is found (whichever comes first).  If the C<"## no critic">
-comment is on the same line as a code statement, then only that line of code
-is overlooked.  To direct perlcritic to ignore the C<"## no critic"> comments,
-use the C<-force> option.
-
-A bare C<"## no critic"> comment disables all the active Policies.  If you
-wish to disable only specific Policies, add a list of Policy names as
-arguments, just as you would for the C<"no strict"> or C<"no warnings">
-pragmas.  For example, this would disable the C<ProhibitEmptyQuotes> and
-C<ProhibitPostfixControls> policies until the end of the block or until the
-next C<"## use critic"> comment (whichever comes first):
+The C<"## no critic"> comments direct Perl::Critic to ignore the
+remaining lines of code until the end of the current block, or until a
+C<"## use critic"> comment is found (whichever comes first).  If the
+C<"## no critic"> comment is on the same line as a code statement,
+then only that line of code is overlooked.  To direct perlcritic to
+ignore the C<"## no critic"> comments, use the C<-force> option.
+
+A bare C<"## no critic"> comment disables all the active Policies.  If
+you wish to disable only specific Policies, add a list of Policy names
+as arguments, just as you would for the C<"no strict"> or C<"no
+warnings"> pragmas.  For example, this would disable the
+C<ProhibitEmptyQuotes> and C<ProhibitPostfixControls> policies until
+the end of the block or until the next C<"## use critic"> comment
+(whichever comes first):
 
   ## no critic (EmptyQuotes, PostfixControls)
 
@@ -917,9 +946,9 @@ next C<"## use critic"> comment (whichever comes first):
   # Still subjected to ValuesAndExpression::RequireNumberSeparators
   $long_int = 10000000000;
 
-Since the Policy names are matched against the C<"## no critic"> arguments as
-regular expressions, you can abbreviate the Policy names or disable an entire
-family of Policies in one shot like this:
+Since the Policy names are matched against the C<"## no critic">
+arguments as regular expressions, you can abbreviate the Policy names
+or disable an entire family of Policies in one shot like this:
 
   ## no critic (NamingConventions)
 
@@ -929,127 +958,127 @@ family of Policies in one shot like this:
   # Now exempt from NamingConventions::ProhibitMixedCaseSubs
   sub camelHumpSub {}
 
-The argument list must be enclosed in parentheses and must contain one or more
-comma-separated barewords (e.g. don't use quotes).  The C<"## no critic">
-pragmas can be nested, and Policies named by an inner pragma will be disabled
-along with those already disabled an outer pragma.
+The argument list must be enclosed in parentheses and must contain one
+or more comma-separated barewords (e.g. don't use quotes).  The
+C<"## no critic"> pragmas can be nested, and Policies named by an
+inner pragma will be disabled along with those already disabled an
+outer pragma.
 
-Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to an entire
-block of code.  In those cases, C<"## no critic"> must appear on the line
-where the violation is reported.  For example:
+Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to
+an entire block of code.  In those cases, C<"## no critic"> must
+appear on the line where the violation is reported.  For example:
 
   sub complicated_function {  ## no critic (ProhibitExcessComplexity)
       # Your code here...
   }
 
-Policies such as C<Documentation::RequirePodSections> apply to the entire
-document, in which case violations are reported at line 1.  But if the file
-requires a shebang line, it is impossible to put C<"## no critic"> on the
-first line of the file.  This is a known limitation and it will be addressed
-in a future release.  As a workaround, you can disable the affected policies
-at the command-line or in your F<.perlcriticrc> file.  But beware that this
-will affect the analysis of B<all> files.
+Policies such as C<Documentation::RequirePodSections> apply to the
+entire document, in which case violations are reported at line 1.
 
-Use this feature wisely.  C<"## no critic"> should be used in the smallest
-possible scope, or only on individual lines of code. And you should always be
-as specific as possible about which policies you want to disable (i.e. never
-use a bare C<"## no critic">).  If Perl::Critic complains about your code, try
-and find a compliant solution before resorting to this feature.
+Use this feature wisely.  C<"## no critic"> should be used in the
+smallest possible scope, or only on individual lines of code. And you
+should always be as specific as possible about which policies you want
+to disable (i.e. never use a bare C<"## no critic">).  If Perl::Critic
+complains about your code, try and find a compliant solution before
+resorting to this feature.
 
 
-=head1 THE L<Perl::Critic> PHILOSOPHY
+=head1 THE L<Perl::Critic|Perl::Critic> PHILOSOPHY
 
-Coding standards are deeply personal and highly subjective.  The goal of
-Perl::Critic is to help you write code that conforms with a set of best
-practices.  Our primary goal is not to dictate what those practices are, but
-rather, to implement the practices discovered by others.  Ultimately, you make
-the rules -- Perl::Critic is merely a tool for encouraging consistency.  If
-there is a policy that you think is important or that we have overlooked, we
-would be very grateful for contributions, or you can simply load your own
-private set of policies into Perl::Critic.
+Coding standards are deeply personal and highly subjective.  The goal
+of Perl::Critic is to help you write code that conforms with a set of
+best practices.  Our primary goal is not to dictate what those
+practices are, but rather, to implement the practices discovered by
+others.  Ultimately, you make the rules -- Perl::Critic is merely a
+tool for encouraging consistency.  If there is a policy that you think
+is important or that we have overlooked, we would be very grateful for
+contributions, or you can simply load your own private set of policies
+into Perl::Critic.
 
 
 =head1 EXTENDING THE CRITIC
 
-The modular design of Perl::Critic is intended to facilitate the addition of
-new Policies.  You'll need to have some understanding of L<PPI>, but most
-Policy modules are pretty straightforward and only require about 20 lines of
-code.  Please see the L<Perl::Critic::DEVELOPER> file included in this
-distribution for a step-by-step demonstration of how to create new Policy
-modules.
+The modular design of Perl::Critic is intended to facilitate the
+addition of new Policies.  You'll need to have some understanding of
+L<PPI|PPI>, but most Policy modules are pretty straightforward and
+only require about 20 lines of code.  Please see the
+L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> file included in
+this distribution for a step-by-step demonstration of how to create
+new Policy modules.
 
 If you develop any new Policy modules, feel free to send them to C<<
-<thaljef@cpan.org> >> and I'll be happy to put them into the Perl::Critic
-distribution.  Or if you would like to work on the Perl::Critic project
-directly, check out our repository at L<http://perlcritic.tigris.org>.  To
-subscribe to our mailing list, send a message to C<<
-<dev-subscribe@perlcritic.tigris.org> >>.
+<thaljef@cpan.org> >> and I'll be happy to put them into the
+Perl::Critic distribution.  Or if you would like to work on the
+Perl::Critic project directly, check out our repository at
+L<http://perlcritic.tigris.org>.  To subscribe to our mailing list,
+send a message to C<< <dev-subscribe@perlcritic.tigris.org> >>.
 
-The Perl::Critic team is also available for hire.  If your organization has
-its own coding standards, we can create custom Policies to enforce your local
-guidelines.  Or if your code base is prone to a particular defect pattern, we
-can design Policies that will help you catch those costly defects B<before>
-they go into production.  To discuss your needs with the Perl::Critic team,
-just contact C<< <thaljef@cpan.org> >>.
+The Perl::Critic team is also available for hire.  If your
+organization has its own coding standards, we can create custom
+Policies to enforce your local guidelines.  Or if your code base is
+prone to a particular defect pattern, we can design Policies that will
+help you catch those costly defects B<before> they go into production.
+To discuss your needs with the Perl::Critic team, just contact C<<
+<thaljef@cpan.org> >>.
 
 
 =head1 PREREQUISITES
 
 Perl::Critic requires the following modules:
 
-L<B::Keywords>
+L<B::Keywords|B::Keywords>
 
-L<Config::Tiny>
+L<Config::Tiny|Config::Tiny>
 
-L<Exception::Class>
+L<Exception::Class|Exception::Class>
 
-L<File::Spec>
+L<File::Spec|File::Spec>
 
-L<File::Spec::Unix>
+L<File::Spec::Unix|File::Spec::Unix>
 
-L<IO::String>
+L<IO::String|IO::String>
 
-L<List::MoreUtils>
+L<List::MoreUtils|List::MoreUtils>
 
-L<List::Util>
+L<List::Util|List::Util>
 
-L<Module::Pluggable>
+L<Module::Pluggable|Module::Pluggable>
 
-L<PPI>
+L<PPI|PPI>
 
-L<Pod::PlainText>
+L<Pod::PlainText|Pod::PlainText>
 
-L<Pod::Usage>
+L<Pod::Usage|Pod::Usage>
 
-L<Readonly>
+L<Readonly|Readonly>
 
-L<Scalar::Util>
+L<Scalar::Util|Scalar::Util>
 
-L<String::Format>
+L<String::Format|String::Format>
 
-L<version>
+L<version|version>
 
 
 The following modules are optional, but recommended for complete
 testing:
 
-L<File::HomeDir>
+L<File::HomeDir|File::HomeDir>
 
-L<File::Which>
+L<File::Which|File::Which>
 
-L<IO::String>
+L<IO::String|IO::String>
 
-L<IPC::Open2>
+L<IPC::Open2|IPC::Open2>
 
-L<Perl::Tidy>
+L<Perl::Tidy|Perl::Tidy>
 
-L<Pod::Spell>
+L<Pod::Spell|Pod::Spell>
 
-L<Test::Pod>
+L<Test::Pod|Test::Pod>
 
-L<Test::Pod::Coverage>
+L<Test::Pod::Coverage|Test::Pod::Coverage>
 
-L<Text::ParseWords>
+L<Text::ParseWords|Text::ParseWords>
 
 
 =head1 CONTACTING THE DEVELOPMENT TEAM
@@ -1059,51 +1088,52 @@ C<< <users-subscribe@perlcritic.tigris.org> >>.  See also
 L<the archives|http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
 You can also contact the author at C<< <thaljef@cpan.org> >>.
 
-At least one member of the development team has started hanging around in
-L<irc://irc.perl.org/#perlcritic>.
+At least one member of the development team has started hanging around
+in L<irc://irc.perl.org/#perlcritic>.
 
 
 =head1 SEE ALSO
 
-There are a number of distributions of additional Policies available.  A few
-are listed here:
+There are a number of distributions of additional Policies available.
+A few are listed here:
 
-L<Perl::Critic::More>
+L<Perl::Critic::More|Perl::Critic::More>
 
-L<Perl::Critic::Bangs>
+L<Perl::Critic::Bangs|Perl::Critic::Bangs>
 
-L<Perl::Critic::Lax>
+L<Perl::Critic::Lax|Perl::Critic::Lax>
 
-L<Perl::Critic::StricterSubs>
+L<Perl::Critic::StricterSubs|Perl::Critic::StricterSubs>
 
-L<Perl::Critic::Swift>
+L<Perl::Critic::Swift|Perl::Critic::Swift>
 
-L<Perl::Critic::Tics>
+L<Perl::Critic::Tics|Perl::Critic::Tics>
 
 These distributions enable you to use Perl::Critic in your unit tests:
 
-L<Test::Perl::Critic>
+L<Test::Perl::Critic|Test::Perl::Critic>
 
-L<Test::Perl::Critic::Progressive>
+L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive>
 
 There are also a couple of distributions that will install all the
 Perl::Critic related modules known to the development team:
 
-L<Bundle::Perl::Critic>
+L<Bundle::Perl::Critic|Bundle::Perl::Critic>
 
-L<Task::Perl::Critic>
+L<Task::Perl::Critic|Task::Perl::Critic>
 
-If you want to make sure you have absolutely everything, you can use these:
+If you want to make sure you have absolutely everything, you can use
+these:
 
-L<Bundle::Perl::Critic::IncludingOptionalDependencies>
+L<Bundle::Perl::Critic::IncludingOptionalDependencies|Bundle::Perl::Critic::IncludingOptionalDependencies>
 
-L<Task::Perl::Critic::IncludingOptionalDependencies>
+L<Task::Perl::Critic::IncludingOptionalDependencies|Task::Perl::Critic::IncludingOptionalDependencies>
 
 
 =head1 BUGS
 
-Scrutinizing Perl code is hard for humans, let alone machines.  If you find
-any bugs, particularly false-positives or false-negatives from a
+Scrutinizing Perl code is hard for humans, let alone machines.  If you
+find any bugs, particularly false-positives or false-negatives from a
 Perl::Critic::Policy, please submit them to
 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.  Thanks.
 
@@ -1113,7 +1143,8 @@ particular block of code.
 
 =head1 CREDITS
 
-Adam Kennedy - For creating L<PPI>, the heart and soul of L<Perl::Critic>.
+Adam Kennedy - For creating L<PPI|PPI>, the heart and soul of
+L<Perl::Critic|Perl::Critic>.
 
 Damian Conway - For writing B<Perl Best Practices>, finally :)
 
@@ -1127,8 +1158,8 @@ Giuseppe Maxia - For all the great ideas and positive encouragement.
 
 and Sharon, my wife - For putting up with my all-night code sessions.
 
-Thanks also to the Perl Foundation for providing a grant to support Chris
-Dolan's project to implement twenty PBP policies.
+Thanks also to the Perl Foundation for providing a grant to support
+Chris Dolan's project to implement twenty PBP policies.
 L<http://www.perlfoundation.org/april_1_2007_new_grant_awards>
 
 
@@ -1141,9 +1172,9 @@ Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 
-This program is free software; you can redistribute it and/or modify it under
-the same terms as Perl itself.  The full text of this license can be found in
-the LICENSE file included with this module.
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.  The full text of this license
+can be found in the LICENSE file included with this module.
 
 =cut
 
index e12f696..5c92b2d 100644 (file)
@@ -751,11 +751,11 @@ Perl::Critic::Config - The final derived Perl::Critic configuration, combined fr
 =head1 DESCRIPTION
 
 Perl::Critic::Config takes care of finding and processing
-user-preferences for L<Perl::Critic>.  The Config object defines which
-Policy modules will be loaded into the Perl::Critic engine and how
-they should be configured.  You should never really need to
-instantiate Perl::Critic::Config directly because the Perl::Critic
-constructor will do it for you.
+user-preferences for L<Perl::Critic|Perl::Critic>.  The Config object
+defines which Policy modules will be loaded into the Perl::Critic
+engine and how they should be configured.  You should never really
+need to instantiate Perl::Critic::Config directly because the
+Perl::Critic constructor will do it for you.
 
 =head1 CONSTRUCTOR
 
@@ -806,8 +806,8 @@ Config, irrespective of the severity settings.  You can use it in
 conjunction with the C<-include> option.  Note that C<-exclude> takes
 precedence over C<-include> when a Policy matches both patterns.
 
-B<-single-policy> is a string C<PATTERN>.  Only the policy that matches
-C<m/$PATTERN/imx> will be used.  This value overrides the
+B<-single-policy> is a string C<PATTERN>.  Only the policy that
+matches C<m/$PATTERN/imx> will be used.  This value overrides the
 C<-severity>, C<-theme>, C<-include>, C<-exclude>, and C<-only>
 options.
 
@@ -844,14 +844,15 @@ comments.  See L<Perl::Critic/"BENDING THE RULES"> for more
 information.
 
 B<-verbose> can be a positive integer (from 1 to 10), or a literal
-format specification.  See L<Perl::Critic::Violations> for an
+format specification.  See
+L<Perl::Critic::Violations|Perl::Critic::Violations> for an
 explanation of format specifications.
 
 B<-color> is not used by Perl::Critic but is provided for the benefit
-of L<perlcritic>.
+of L<perlcritic|perlcritic>.
 
-B<-criticism-fatal> is not used by Perl::Critic but is provided for the benefit
-of L<criticism>.
+B<-criticism-fatal> is not used by Perl::Critic but is provided for
+the benefit of L<criticism|criticism>.
 
 
 
@@ -867,9 +868,10 @@ Creates a Policy object and loads it into this Config.  If the object
 cannot be instantiated, it will throw a fatal exception.  Otherwise,
 it returns a reference to this Critic.
 
-B<-policy> is the name of a L<Perl::Critic::Policy> subclass
-module.  The C<'Perl::Critic::Policy'> portion of the name can be
-omitted for brevity.  This argument is required.
+B<-policy> is the name of a
+L<Perl::Critic::Policy|Perl::Critic::Policy> subclass module.  The
+C<'Perl::Critic::Policy'> portion of the name can be omitted for
+brevity.  This argument is required.
 
 B<-params> is an optional reference to a hash of Policy parameters.
 The contents of this hash reference will be passed into to the
@@ -913,8 +915,8 @@ Returns the value of the C<-single-policy> attribute for this Config.
 
 =item C< theme() >
 
-Returns the L<Perl::Critic::Theme> object that was created for
-this Config.
+Returns the L<Perl::Critic::Theme|Perl::Critic::Theme> object that was
+created for this Config.
 
 =item C< top() >
 
@@ -954,18 +956,19 @@ have been installed.
 
 Most of the settings for Perl::Critic and each of the Policy modules
 can be controlled by a configuration file.  The default configuration
-file is called F<.perlcriticrc>.  L<Perl::Critic::Config> will look
-for this file in the current directory first, and then in your home
-directory.  Alternatively, you can set the C<PERLCRITIC> environment
-variable to explicitly point to a different file in another location.
-If none of these files exist, and the C<-profile> option is not given
-to the constructor, then all Policies will be loaded with their
-default configuration.
-
-The format of the configuration file is a series of INI-style
-blocks that contain key-value pairs separated by '='. Comments
-should start with '#' and can be placed on a separate line or after
-the name-value pairs if you desire.
+file is called F<.perlcriticrc>.
+L<Perl::Critic::Config|Perl::Critic::Config> will look for this file
+in the current directory first, and then in your home directory.
+Alternatively, you can set the C<PERLCRITIC> environment variable to
+explicitly point to a different file in another location.  If none of
+these files exist, and the C<-profile> option is not given to the
+constructor, then all Policies will be loaded with their default
+configuration.
+
+The format of the configuration file is a series of INI-style blocks
+that contain key-value pairs separated by '='. Comments should start
+with '#' and can be placed on a separate line or after the name-value
+pairs if you desire.
 
 Default settings for Perl::Critic itself can be set B<before the first
 named block.>  For example, putting any or all of these at the top of
@@ -996,8 +999,8 @@ C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
 module that implements the policy.  The Policy modules distributed
 with Perl::Critic have been grouped into categories according to the
 table of contents in Damian Conway's book B<Perl Best Practices>. For
-brevity, you can omit the C<'Perl::Critic::Policy'> part of the
-module name.
+brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
+name.
 
 C<severity> is the level of importance you wish to assign to the
 Policy.  All Policy modules are defined with a default severity value
@@ -1066,21 +1069,22 @@ that is included in this F<t/examples> directory of this distribution.
 
 A large number of Policy modules are distributed with Perl::Critic.
 They are described briefly in the companion document
-L<Perl::Critic::PolicySummary> and in more detail in the individual
-modules themselves.
+L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
+detail in the individual modules themselves.
 
 =head1 POLICY THEMES
 
-Each Policy is defined with one or more "themes".  Themes can be used to
-create arbitrary groups of Policies.  They are intended to provide an
-alternative mechanism for selecting your preferred set of Policies.  For
-example, you may wish disable a certain subset of Policies when analyzing test
-scripts.  Conversely, you may wish to enable only a specific subset of
-Policies when analyzing modules.
+Each Policy is defined with one or more "themes".  Themes can be used
+to create arbitrary groups of Policies.  They are intended to provide
+an alternative mechanism for selecting your preferred set of Policies.
+For example, you may wish disable a certain subset of Policies when
+analyzing test scripts.  Conversely, you may wish to enable only a
+specific subset of Policies when analyzing modules.
 
 The Policies that ship with Perl::Critic are have been broken into the
-following themes.  This is just our attempt to provide some basic logical
-groupings.  You are free to invent new themes that suit your needs.
+following themes.  This is just our attempt to provide some basic
+logical groupings.  You are free to invent new themes that suit your
+needs.
 
     THEME             DESCRIPTION
     --------------------------------------------------------------------------
@@ -1099,9 +1103,10 @@ and the themes that are associated with each one.  You can also change
 the theme for any Policy in your F<.perlcriticrc> file.  See the
 L<"CONFIGURATION"> section for more information about that.
 
-Using the C<-theme> option, you can combine theme names with mathematical and
-boolean operators to create an arbitrarily complex expression that represents
-a custom "set" of Policies.  The following operators are supported
+Using the C<-theme> option, you can combine theme names with
+mathematical and boolean operators to create an arbitrarily complex
+expression that represents a custom "set" of Policies.  The following
+operators are supported
 
    Operator       Alternative         Meaning
    ----------------------------------------------------------------------------
@@ -1110,7 +1115,8 @@ a custom "set" of Policies.  The following operators are supported
    +              or                  Union
 
 Operator precedence is the same as that of normal mathematics.  You
-can also use parenthesis to enforce precedence.  Here are some examples:
+can also use parenthesis to enforce precedence.  Here are some
+examples:
 
    Expression                  Meaning
    ----------------------------------------------------------------------------
@@ -1130,14 +1136,15 @@ can also use parenthesis to enforce precedence.  Here are some examples:
                                     AND "complexity"
    (pbp not bugs) and complexity  Ditto
 
-Theme names are case-insensitive.  If C<-theme> is set to an empty string,
-then it is equivalent to the set of all Policies.  A theme name that doesn't
-exist is equivalent to an empty set.  Please See
+Theme names are case-insensitive.  If C<-theme> is set to an empty
+string, then it is equivalent to the set of all Policies.  A theme
+name that doesn't exist is equivalent to an empty set.  Please See
 L<http://en.wikipedia.org/wiki/Set> for a discussion on set theory.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::OptionsProcessor>, L<Perl::Critic::UserProfile>
+L<Perl::Critic::OptionsProcessor|Perl::Critic::OptionsProcessor>,
+L<Perl::Critic::UserProfile|Perl::Critic::UserProfile>
 
 
 =head1 AUTHOR
index 11f04b6..607e9f6 100644 (file)
@@ -17,34 +17,38 @@ Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules.
 =head1 DESCRIPTION
 
 For developers who want to create custom coding standards, the
-following tells how to create a Policy module for L<Perl::Critic>.
-Although the Perl::Critic distribution already includes a number of
-Policies based on Damian Conway's book I<Perl Best Practices> (which
-will be referred to via "I<PBP>" from here on), Perl::Critic is not
-limited to his guidelines and can be used to enforce any practice,
-preference, or style that you want to follow.  You can even write
-Policies to enforce contradictory guidelines.  All you need to do is
-write a corresponding L<Perl::Critic::Policy> subclass, which may
+following tells how to create a Policy module for
+L<Perl::Critic|Perl::Critic>.  Although the Perl::Critic distribution
+already includes a number of Policies based on Damian Conway's book
+I<Perl Best Practices> (which will be referred to via "I<PBP>" from
+here on), Perl::Critic is not limited to his guidelines and can be
+used to enforce any practice, preference, or style that you want to
+follow.  You can even write Policies to enforce contradictory
+guidelines.  All you need to do is write a corresponding
+L<Perl::Critic::Policy|Perl::Critic::Policy> subclass, which may
 require as little as 10 lines of code.
 
 
 =head1 BACKGROUND
 
-The heart of Perl::Critic is L<PPI>, a parser and lexer for Perl.  PPI
-transforms Perl source code into a Document Object Model (DOM).  Each
-token in the document is represented by a PPI class, such as
-L<PPI::Token::Operator> or L<PPI::Token::Word>, and then organized
-into structure classes, like L<PPI::Statement::Expression> and
-L<PPI::Structure::Subroutine>. The root node of the hierarchy is the
-L<PPI::Document>.
-
-The L<Perl::Critic> engine traverses each node in the L<PPI::Document>
-tree and invokes each of the L<Perl::Critic::Policy> subclasses at the
+The heart of Perl::Critic is L<PPI|PPI>, a parser and lexer for Perl.
+PPI transforms Perl source code into a Document Object Model (DOM).
+Each token in the document is represented by a PPI class, such as
+L<PPI::Token::Operator|PPI::Token::Operator> or
+L<PPI::Token::Word|PPI::Token::Word>, and then organized into
+structure classes, like
+L<PPI::Statement::Expression|PPI::Statement::Expression> and
+L<PPI::Structure::Subroutine|PPI::Structure::Subroutine>. The root
+node of the hierarchy is the L<PPI::Document|PPI::Document>.
+
+The L<Perl::Critic|Perl::Critic> engine traverses each node in the
+L<PPI::Document|PPI::Document> tree and invokes each of the
+L<Perl::Critic::Policy|Perl::Critic::Policy> subclasses at the
 appropriate node.  The Policy can inspect the node, look at the
 surrounding nodes, and do whatever else it wants.  If the Policy
 decides that that a coding standard has been violated, it returns one
-or more L<Perl::Critic::Violation> objects.  If there are no
-violations, then the Policy returns nothing.
+or more L<Perl::Critic::Violation|Perl::Critic::Violation> objects.
+If there are no violations, then the Policy returns nothing.
 
 Policies are usually written based on existing policies, so let's look
 at one to see how it works.  The F<RequireBlockGrep.pm> Policy is
@@ -57,20 +61,21 @@ this Policy are discussed in detail in I<PBP>.
 =head1 EXAMPLE POLICY
 
 First, the Policy module needs to have a name.  Perl::Critic uses
-L<Module::Pluggable> to automatically discover all modules in the
-C<Perl::Critic::Policy> namespace.  Also, we've adopted the convention
-of grouping Policies into directories according to the chapters of
-I<PBP>.  Since the goal of this Policy is to enforce the use of block
-arguments to C<grep> and it comes from the "Builtin Functions" chapter
-of I<PBP>, we call it
+L<Module::Pluggable|Module::Pluggable> to automatically discover all
+modules in the C<Perl::Critic::Policy> namespace.  Also, we've adopted
+the convention of grouping Policies into directories according to the
+chapters of I<PBP>.  Since the goal of this Policy is to enforce the
+use of block arguments to C<grep> and it comes from the "Builtin
+Functions" chapter of I<PBP>, we call it
 C<"Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep">.
 
     package Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep;
 
 Next, we set some pragmas and load the modules that we'll need.  All
-Policy modules inherit from the L<Perl::Critic::Policy> class, which
-provides no-op implementations of the basic methods.  Our job is to
-override these methods to make them do something useful.
+Policy modules inherit from the
+L<Perl::Critic::Policy|Perl::Critic::Policy> class, which provides
+no-op implementations of the basic methods.  Our job is to override
+these methods to make them do something useful.
 
 Technically, C<use strict> and C<use warnings> are optional, but we
 don't want Perl::Critic to be a hypocrite, now do we?
@@ -91,19 +96,19 @@ what's wrong."  The explanation can be either a string with further
 details, or a reference to an array of integers that correspond to
 page numbers in I<PBP>.  We make them read-only because they never
 change.  (See
-L<Perl::Critic::ValuesAndExpressions::ProhibitConstantPragma> for why
-we don't C<use constant>.)
+L<Perl::Critic::ValuesAndExpressions::ProhibitConstantPragma|Perl::Critic::ValuesAndExpressions::ProhibitConstantPragma>
+for why we don't C<use constant>.)
 
     Readonly::Scalar my $DESC => q{Expression form of "grep"};
     Readonly::Scalar my $EXPL => [ 169 ];
 
 Most policies don't need to override the C<initialize_if_enabled()>
-method provided by L<Perl::Critic::Policy>.  However, if your Policy
-is configurable via F<.perlcriticrc>, you should implement a
-C<supported_parameters()> method and need to implement
-C<initialize_if_enabled()> to examine the C<$config> values.  Since
-this Policy isn't configurable, we'll declare that by providing an
-implementation of C<supported_parameters()> that returns an empty
+method provided by L<Perl::Critic::Policy|Perl::Critic::Policy>.
+However, if your Policy is configurable via F<.perlcriticrc>, you
+should implement a C<supported_parameters()> method and need to
+implement C<initialize_if_enabled()> to examine the C<$config> values.
+Since this Policy isn't configurable, we'll declare that by providing
+an implementation of C<supported_parameters()> that returns an empty
 list.
 
     sub supported_parameters { return ()                  }
@@ -113,8 +118,9 @@ integer indicating the severity of violating this Policy.  Severity
 values range from 1 to 5, where 5 is the "most severe."  In general,
 level 5 is reserved for things that are frequently misused and/or
 cause bugs.  Level 1 is for things that are highly subjective or
-purely cosmetic.  The L<Perl::Critic::Utils> package exports several
-severity constants that you can use here via the C<:severities> tag.
+purely cosmetic.  The L<Perl::Critic::Utils|Perl::Critic::Utils>
+package exports several severity constants that you can use here via
+the C<:severities> tag.
 
     sub default_severity     { return $SEVERITY_HIGH      }
 
@@ -132,29 +138,31 @@ If you're publishing a suite of custom Policies, we suggest that you
 create a unique theme that covers all the Policies in the
 distribution.  That way, users can easily enable or disable all of
 your policies at once.  For example, Policies in the
-L<Perl::Critic::More> distribution all have a C<"more"> theme.
+L<Perl::Critic::More|Perl::Critic::More> distribution all have a
+C<"more"> theme.
 
 Next, we indicate what elements of the code this Policy will analyze,
 like statements or variables or conditionals or POD.  These elements
-are specified as PPI classes such as L<PPI::Statement>,
-L<PPI::Token::Symbol>, L<PPI::Structure::Conditional> or
-L<PPI::Token::Pod> respectively.  The applies_to() method returns a
-list of PPI package names.  (You can get that list of available
-package names via C<perldoc PPI>.)  As Perl::Critic traverses the
-document, it will call the C<violates()> method from this module
-whenever it encounters one of the PPI types that are given here.  In
-this case, we just want to test calls to C<grep>.  Since the token
-"grep" is a L<PPI::Token::Word>, we return that package name from the
-C<applies_to()> method.
+are specified as PPI classes such as L<PPI::Statement|PPI::Statement>,
+L<PPI::Token::Symbol|PPI::Token::Symbol>,
+L<PPI::Structure::Conditional|PPI::Structure::Conditional> or
+L<PPI::Token::Pod|PPI::Token::Pod> respectively.  The applies_to()
+method returns a list of PPI package names.  (You can get that list of
+available package names via C<perldoc PPI>.)  As Perl::Critic
+traverses the document, it will call the C<violates()> method from
+this module whenever it encounters one of the PPI types that are given
+here.  In this case, we just want to test calls to C<grep>.  Since the
+token "grep" is a L<PPI::Token::Word|PPI::Token::Word>, we return that
+package name from the C<applies_to()> method.
 
     sub applies_to           { return 'PPI::Token::Word'  }
 
 If your Policy needs to analyze several different types of elements,
 the C<applies_to> method may return the name of several PPI packages.
 If your Policy needs to examine the file as a whole, then the
-C<applies_to> method should return L<PPI::Document>.  Since there is
-only one PPI::Document element, your Policy would only be invoked once
-per file.
+C<applies_to> method should return L<PPI::Document|PPI::Document>.
+Since there is only one PPI::Document element, your Policy would only
+be invoked once per file.
 
 Now comes the interesting part.  The C<violates()> method does all the
 work.  It is always called with 2 arguments: a reference to the
@@ -170,11 +178,11 @@ by assigning to C<undef>.
 
 The violates() method then often performs some tests to make sure we
 have the right "type" of element.  In our example, we know that the
-element will be a L<PPI::Token::Word> because that's what we declared
-back in the C<applies_to()> method.  However, we didn't specify
-exactly which "word" we were looking for.  Evaluating a PPI element in
-a string context returns the literal form of the code.  (You can also
-use the c<content()> method.)  So we make sure that this
+element will be a L<PPI::Token::Word|PPI::Token::Word> because that's
+what we declared back in the C<applies_to()> method.  However, we
+didn't specify exactly which "word" we were looking for.  Evaluating a
+PPI element in a string context returns the literal form of the code.
+(You can also use the c<content()> method.)  So we make sure that this
 PPI::Token::Word is, in fact, "grep".  If it's not, then we don't'
 need to bother examining it.
 
@@ -185,18 +193,18 @@ called on object references.  It is possible for someone to declare a
 bareword hash key as C<<%hash = ( grep => 'foo' )>>.  We don't want to
 test those types of elements because they don't represent function
 calls to C<grep>.  So we use one of handy utility functions from
-L<Perl::Critic::Utils> to make sure that this "grep" is actually in
-the right context.  (The C<is_function_call()> subroutine is brought
-in via the C<:classification> tag.)
+L<Perl::Critic::Utils|Perl::Critic::Utils> to make sure that this
+"grep" is actually in the right context.  (The C<is_function_call()>
+subroutine is brought in via the C<:classification> tag.)
 
         return if ! is_function_call($elem);
 
 Now that we know this element is a call to the C<grep> function, we
 can look at the nearby elements to see what kind of arguments are
 being passed to it.  In the following paragraphs, we discuss how to do
-this manually in order to explore L<PPI>; after that, we'll show how
-this Policy actually uses facilities provided by
-L<Perl::Critic::Utils> to get this done.
+this manually in order to explore L<PPI|PPI>; after that, we'll show
+how this Policy actually uses facilities provided by
+L<Perl::Critic::Utils|Perl::Critic::Utils> to get this done.
 
 Every PPI element is linked to its siblings, parent, and children (if
 it has any).  Since those siblings could just be whitespace, we use
@@ -206,11 +214,12 @@ C<snext_sibling> stands for "significant").
         my $sib = $elem->snext_sibling() or return;
 
 In Perl, the parenthesis around argument lists are usually optional,
-and PPI packs the elements into a L<PPI::Structure::List> object when
-parentheses are used.  So if the sibling is a PPI::Structure::List, we
-pull out the first (significant) child of that list.  This child will
-be the first argument to C<grep>.  If parentheses were not used, then
-the sibling itself is the first argument.
+and PPI packs the elements into a
+L<PPI::Structure::List|PPI::Structure::List> object when parentheses
+are used.  So if the sibling is a PPI::Structure::List, we pull out
+the first (significant) child of that list.  This child will be the
+first argument to C<grep>.  If parentheses were not used, then the
+sibling itself is the first argument.
 
         my $arg = $sib->isa('PPI::Structure::List') ? $sib->schild(0) : $sib;
 
@@ -222,17 +231,18 @@ the C<:ppi> tag.  So we use that instead.
 
 Finally, we now have a reference to the first argument to C<grep>.  If
 that argument is a block (i.e. something in curly braces), then it
-will be a L<PPI::Structure::Block>, in which case our Policy is
-satisfied and we just return nothing.
+will be a L<PPI::Structure::Block|PPI::Structure::Block>, in which
+case our Policy is satisfied and we just return nothing.
 
         return if !$arg;
         return if $arg->isa('PPI::Structure::Block');
 
-But if it is not a L<PPI::Structure::Block>, then we know that this
-call to C<grep> must be using the expression form, and that violates
-our Policy.  So we create and return a new L<Perl::Critic::Violation>
-object via the L<Perl::Critic::Policy/"violation"> method, passing in
-the description, explanation, and a reference to the PPI element that
+But if it is not a L<PPI::Structure::Block|PPI::Structure::Block>,
+then we know that this call to C<grep> must be using the expression
+form, and that violates our Policy.  So we create and return a new
+L<Perl::Critic::Violation|Perl::Critic::Violation> object via the
+L<Perl::Critic::Policy/"violation"> method, passing in the
+description, explanation, and a reference to the PPI element that
 caused the violation.  And that's all there is to it!
 
         return $self->violation( $DESC, $EXPL, $elem );
@@ -269,41 +279,43 @@ bad code.  Here's an example:
     =cut
 
 When your policy has a section like this, users can invoke
-L<perlcritic> with a C<--verbose> parameter of C<10> or C<11> to see
-it along with the rest of the output for violations of your policy.
+L<perlcritic|perlcritic> with a C<--verbose> parameter of C<10> or
+C<11> to see it along with the rest of the output for violations of
+your policy.
 
 
 =head1 MAKING YOUR POLICY CONFIGURABLE
 
-L<Perl::Critic> takes care of gathering configuration information for
-your Policy, from whatever source the user specifies.  (See
-L<Perl::Critic/"CONFIGURATION"> for the details of how a user specifies
-the values you're going to receive.)  What your Policy ends up
-receiving for the value of a parameter is a string with leading and
+L<Perl::Critic|Perl::Critic> takes care of gathering configuration
+information for your Policy, from whatever source the user specifies.
+(See L<Perl::Critic/"CONFIGURATION"> for the details of how a user
+specifies the values you're going to receive.)  What your Policy ends
+up receiving for the value of a parameter is a string with leading and
 trailing whitespace removed.  By default, you will need to handle
 conversion of that string to a useful form yourself.  However, if you
 provide some metadata about your parameters, the parameter handling
 will be taken care of for you.  (Additionally, tools that deal with
 Policies themselves can use this information to enhance their
-functionality.  See the L<perlcritic> C<--profile-proto> option for an
-example.)
+functionality.  See the L<perlcritic|perlcritic> C<--profile-proto>
+option for an example.)
 
 You can look at
-L<Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse>
+L<Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse|Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse>
 for a simple example of a configurable Policy and
-L<Perl::Critic::Policy::Documentation::RequirePodSections> for a more
-complex one.
+L<Perl::Critic::Policy::Documentation::RequirePodSections|Perl::Critic::Policy::Documentation::RequirePodSections>
+for a more complex one.
 
 =head2 Do It All Yourself
 
 The C<initialize_if_enabled()> method for a Policy receives one
-argument: an instance of L<Perl::Critic::PolicyConfig>.  This method
+argument: an instance of
+L<Perl::Critic::PolicyConfig|Perl::Critic::PolicyConfig>.  This method
 is only called if the user's configuration has enabled the policy.  It
 returns a boolean stating whether the Policy should continue to be
 enabled.  Generally, the only reason to return C<$FALSE> is when some
 external requirement is missing.  For example,
-L<Perl::Critic::Policy::CodeLayout::RequireTidyCode> disables itself
-if L<Perl::Tidy> is not installed.
+L<Perl::Critic::Policy::CodeLayout::RequireTidyCode|Perl::Critic::Policy::CodeLayout::RequireTidyCode>
+disables itself if L<Perl::Tidy|Perl::Tidy> is not installed.
 
 A basic, do-nothing implementation of C<initialize_if_enabled()> would
 be:
@@ -350,10 +362,10 @@ prefixed with an underscore.  E.g.
 
 Often, you'll want to convert the configuration values into something
 more useful.  In this example, C<selections> is supposed to be a list
-of integers.  L<Perl::Critic::Utils> contains a number of functions
-that can help you with this.  Assuming that C<violates()> wants to
-have C<selections> as an array, you'll want to have something like
-this:
+of integers.  L<Perl::Critic::Utils|Perl::Critic::Utils> contains a
+number of functions that can help you with this.  Assuming that
+C<violates()> wants to have C<selections> as an array, you'll want to
+have something like this:
 
     use Perl::Critic::Utils qw{ :booleans :characters :data_conversion };
 
@@ -383,7 +395,7 @@ like this:
 
 For an example of a Policy that has some simple, but non-standard
 configuration handling, see
-L<Perl::Critic::Policy::CodeLayout::RequireTidyCode>.
+L<Perl::Critic::Policy::CodeLayout::RequireTidyCode|Perl::Critic::Policy::CodeLayout::RequireTidyCode>.
 
 
 =head2 Note On Constructors
@@ -394,11 +406,11 @@ the base constructor; as long as the Policy ended up being a blessed
 hash reference, everything was fine.  Unfortunately, this meant that
 Policies would be loaded and their prerequisites would be C<use>d,
 even if the Policy wasn't enabled, slowing things down.  Also, this
-severely restricted the core of L<Perl::Critic>'s ability to enhance
-things.  Use of constructors is deprecated and is incompatible with
-C<supported_parameters()> metadata below.  Kindly use
-C<initialize_if_enabled()>, instead, to do any sort of set up that you
-need.
+severely restricted the core of L<Perl::Critic|Perl::Critic>'s ability
+to enhance things.  Use of constructors is deprecated and is
+incompatible with C<supported_parameters()> metadata below.  Kindly
+use C<initialize_if_enabled()>, instead, to do any sort of set up that
+you need.
 
 
 
@@ -406,8 +418,8 @@ need.
 
 As minimum for a well behaved Policy, you should implement
 C<supported_parameters()> in order to tell the rest of C<Perl::Critic>
-what configuration values the Policy looks for, even if it is only to say
-that the Policy is not configurable.  In the simple form, this
+what configuration values the Policy looks for, even if it is only to
+say that the Policy is not configurable.  In the simple form, this
 function returns a list of the names of the parameters the Policy
 supports.  So, for an non-configurable Policy, as in the
 C<RequireBlockGrep> example above, this looked like
@@ -485,8 +497,9 @@ declaration, the parsed and validated value can be accessed via
 C<<$self->{_allowed_types}>>.
 
 The behaviors provide additional functionality to C<Perl::Critic>; for
-more on this, see L<Perl::Critic::PolicyParameter> and
-L<Perl::Critic::PolicyParameter::Behavior>.
+more on this, see
+L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> and
+L<Perl::Critic::PolicyParameter::Behavior|Perl::Critic::PolicyParameter::Behavior>.
 
 The following discusses each of the supported behaviors and the
 options they support.  For the full details of a behavior, see the
@@ -495,7 +508,8 @@ documentation for the implementing class.
 
 =head3 "string"
 
-Implemented in L<Perl::Critic::PolicyParameter::Behavior::String>.
+Implemented in
+L<Perl::Critic::PolicyParameter::Behavior::String|Perl::Critic::PolicyParameter::Behavior::String>.
 
 The most basic of behaviors, the value of the parameter will be stored
 in the Policy as a string.
@@ -529,7 +543,8 @@ This behavior is not configurable.
 
 =head3 "boolean"
 
-Implemented in L<Perl::Critic::PolicyParameter::Behavior::Boolean>.
+Implemented in
+L<Perl::Critic::PolicyParameter::Behavior::Boolean|Perl::Critic::PolicyParameter::Behavior::Boolean>.
 
 The value of the parameter will be either L<Perl::Critic::Utils/$TRUE>
 or L<Perl::Critic::Utils/$FALSE>.
@@ -566,15 +581,16 @@ This behavior is not configurable.
 
 =head3 "integer"
 
-Implemented in L<Perl::Critic::PolicyParameter::Behavior::Integer>.
+Implemented in
+L<Perl::Critic::PolicyParameter::Behavior::Integer|Perl::Critic::PolicyParameter::Behavior::Integer>.
 
 The value is validated against C<m/ \A [-+]? [1-9] [\d_]* \z /xms>
 (with an special check for "0").  Notice that this means that
 underscores are allowed in input values as with Perl numeric literals.
 
-This takes two options, C<integer_minimum> and
-C<integer_maximum>, which specify endpoints of an inclusive range to
-restrict the value to.  Either, neither, or both may be specified.
+This takes two options, C<integer_minimum> and C<integer_maximum>,
+which specify endpoints of an inclusive range to restrict the value
+to.  Either, neither, or both may be specified.
 
 =head4 C<supported_parameters()> example
 
@@ -608,7 +624,8 @@ restrict the value to.  Either, neither, or both may be specified.
 
 =head3 "string list"
 
-Implemented in L<Perl::Critic::PolicyParameter::Behavior::StringList>.
+Implemented in
+L<Perl::Critic::PolicyParameter::Behavior::StringList|Perl::Critic::PolicyParameter::Behavior::StringList>.
 
 The values will be derived by splitting the input string on blanks.
 (See L<Perl::Critic::Utils/"words_from_string">.) The parameter will
@@ -616,10 +633,9 @@ be stored as a reference to a hash, with the values being the keys.
 
 This takes one optional option, C<always_present_values>, of a
 reference to an array of strings that will always be included in the
-parameter value, e.g. if the value of this option is
-C<[ qw{ a b c } ]> and the user specifies a value of C<'c d e'>, then
-the value of the parameter will contain C<'a'>, C<'b'>, C<'c'>,
-C<'d'>, and C<'e'>.
+parameter value, e.g. if the value of this option is C<[ qw{ a b c }
+]> and the user specifies a value of C<'c d e'>, then the value of the
+parameter will contain C<'a'>, C<'b'>, C<'c'>, C<'d'>, and C<'e'>.
 
 =head4 C<supported_parameters()> example
 
@@ -652,7 +668,8 @@ C<'d'>, and C<'e'>.
 
 =head3 "enumeration"
 
-Implemented in L<Perl::Critic::PolicyParameter::Behavior::Enumeration>.
+Implemented in
+L<Perl::Critic::PolicyParameter::Behavior::Enumeration|Perl::Critic::PolicyParameter::Behavior::Enumeration>.
 
 The values will be derived by splitting the input string on blanks.
 (See L<Perl::Critic::Utils/"words_from_string">.)  Depending upon the
@@ -736,8 +753,10 @@ For example:
         );
     }
 
-A parser is a method on a subclass of L<Perl::Critic::Policy> that
-takes two parameters: the L<Perl::Critic::PolicyParameter> that is
+A parser is a method on a subclass of
+L<Perl::Critic::Policy|Perl::Critic::Policy> that takes two
+parameters: the
+L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> that is
 being specified and the value string provided by the user.  The method
 is responsible for dealing with any default value and for saving the
 parsed value for later use by the C<violates()> method.
@@ -773,7 +792,7 @@ example declaration:
     }
 
 Note that, if the value for the parameter is not valid, an instance of
-L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
+L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
 is thrown.  This allows C<Perl::Critic> to include that problem along
 with any other problems found with the user's configuration in a
 single error message.
@@ -884,18 +903,19 @@ the value of the parameter.
 Certain problems that a Policy detects can be endemic to a particular
 file; if there's one violation, there's likely to be many.  A good
 example of this is
-L<Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict>; if
-there's one line before L<use strict>, there's a good chance that the
-entire file is missing L<use strict>.  In such cases, it's not much
-help to the user to report every single violation.  If you've got such
-a policy, you should override
+L<Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict|Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict>;
+if there's one line before L<use strict>, there's a good chance that
+the entire file is missing L<use strict>.  In such cases, it's not
+much help to the user to report every single violation.  If you've got
+such a policy, you should override
 L<default_maximum_violations_per_document()|Perl::Critic::Policy/"default_maximum_violations_per_document()">
 method to provide a limit.  The user can override this value with a
 value for "maximum_violations_per_document" in their F<.perlcriticrc>.
 
 See the source code for
-L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers>
-and L<Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings>
+L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers|Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers>
+and
+L<Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings|Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings>
 for examples.
 
 
@@ -905,13 +925,13 @@ for examples.
 
 You need to come up with a name for your set of policies.  Sets of
 add-on policies are generally named C<Perl::Critic::I<something>>,
-e.g. L<Perl::Critic::More>.
+e.g. L<Perl::Critic::More|Perl::Critic::More>.
 
 The module representing the distribution will not actually have any
 functionality; it's just documentation and a name for users to use
-when installing via L<CPAN>/L<CPANPLUS>.  The important part is that
-this will include a list of the included policies, with descriptions
-of each.
+when installing via L<CPAN|CPAN>/L<CPANPLUS|CPANPLUS>.  The important
+part is that this will include a list of the included policies, with
+descriptions of each.
 
 A typical implementation will look like:
 
@@ -941,7 +961,7 @@ A typical implementation will look like:
 
     =head1 SYNOPSIS
 
-    Some L<Perl::Critic> policies that will help you keep your code
+    Some L<Perl::Critic|Perl::Critic> policies that will help you keep your code
     nice and compliant.
 
 
@@ -951,12 +971,12 @@ A typical implementation will look like:
 
     =over
 
-    =item L<Perl::Critic::Policy::Documentation::Example>
+    =item L<Perl::Critic::Policy::Documentation::Example|Perl::Critic::Policy::Documentation::Example>
 
     Complains about some example documentation issues.  [Severity: 3]
 
 
-    =item L<Perl::Critic::Policy::Variables::Example>
+    =item L<Perl::Critic::Policy::Variables::Example|Perl::Critic::Policy::Variables::Example>
 
     All modules must have at least one variable.  [Severity: 3]
 
@@ -967,7 +987,7 @@ A typical implementation will look like:
     =head1 CONFIGURATION AND ENVIRONMENT
 
     All policies included are in the "example" theme.  See the
-    L<Perl::Critic> documentation for how to make use of this.
+    L<Perl::Critic|Perl::Critic> documentation for how to make use of this.
 
 
 =head2 Themes
@@ -997,7 +1017,7 @@ policy comes from.  For example:
 
     =head1 AFFILIATION
 
-    This policy is part of L<Perl::Critic::Example>.
+    This policy is part of L<Perl::Critic::Example|Perl::Critic::Example>.
 
 
 =head3 CONFIGURATION
@@ -1013,10 +1033,11 @@ only to say:
 
 =head1 HINT
 
-When you're trying to figure out what L<PPI> is going to hand you for
-a chunk of code, there is a F<tools/ppidump> program in the
-L<Perl::Critic> distribution that will help you.  For example, when
-developing the above RequireBlockGrep example, you might want to try
+When you're trying to figure out what L<PPI|PPI> is going to hand you
+for a chunk of code, there is a F<tools/ppidump> program in the
+L<Perl::Critic|Perl::Critic> distribution that will help you.  For
+example, when developing the above RequireBlockGrep example, you might
+want to try
 
     tools/ppidump '@matches = grep /pattern/, @list;'
 
@@ -1029,7 +1050,7 @@ to see the differences between the two cases.
 
 =head1 VERSION
 
-This is part of L<Perl::Critic> version 1.088.
+This is part of L<Perl::Critic|Perl::Critic> version 1.088.
 
 
 =head1 AUTHOR
index d609a78..ea2d048 100644 (file)
@@ -231,10 +231,10 @@ stored C<PPI::Document> instance.
 =head1 CAVEATS
 
 This facade does not implement the overloaded operators from
-L<PPI::Document> (that is, the C<use overload ...> work). Therefore,
-users of this facade must not rely on that syntactic sugar.  So, for
-example, instead of C<my $source = "$doc";> you should write C<my
-$source = $doc->content();>
+L<PPI::Document|PPI::Document> (that is, the C<use overload ...>
+work). Therefore, users of this facade must not rely on that syntactic
+sugar.  So, for example, instead of C<my $source = "$doc";> you should
+write C<my $source = $doc->content();>
 
 Perhaps there is a CPAN module out there which implements a facade
 better than we do here?
@@ -263,9 +263,10 @@ Create a new instance referencing a PPI::Document instance.
 
 =item C<< ppi_document() >>
 
-Accessor for the wrapped PPI::Document instance.  Note that altering this
-instance in any way can cause unpredictable failures in Perl::Critic's
-subsequent analysis because some caches may fall out of date.
+Accessor for the wrapped PPI::Document instance.  Note that altering
+this instance in any way can cause unpredictable failures in
+Perl::Critic's subsequent analysis because some caches may fall out of
+date.
 
 
 =item C<< find($wanted) >>
@@ -287,15 +288,16 @@ Returns the filename for the source code if applicable
 
 =item C<< isa( $classname ) >>
 
-To be compatible with other modules that expect to get a PPI::Document, the
-Perl::Critic::Document class masquerades as the PPI::Document class.
+To be compatible with other modules that expect to get a
+PPI::Document, the Perl::Critic::Document class masquerades as the
+PPI::Document class.
 
 
 =item C<< highest_explicit_perl_version() >>
 
-Returns a L<version> object for the highest Perl version requirement declared
-in the document via a C<use> or C<require> statement.  Returns nothing if
-there is no version statement.
+Returns a L<version|version> object for the highest Perl version
+requirement declared in the document via a C<use> or C<require>
+statement.  Returns nothing if there is no version statement.
 
 
 =back
index 9ee36dd..5abc81e 100644 (file)
@@ -47,13 +47,14 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception - A problem identified by L<Perl::Critic>.
+Perl::Critic::Exception - A problem identified by L<Perl::Critic|Perl::Critic>.
 
 =head1 DESCRIPTION
 
-A base class for all problems discovered by L<Perl::Critic>.  This
-exists to enable differentiating exceptions from L<Perl::Critic> code
-from those originating in other modules.
+A base class for all problems discovered by
+L<Perl::Critic|Perl::Critic>.  This exists to enable differentiating
+exceptions from L<Perl::Critic|Perl::Critic> code from those
+originating in other modules.
 
 This is an abstract class.  It should never be instantiated.
 
@@ -75,6 +76,7 @@ stripped off.
 
 Elliot Shank <perl@galumph.com>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2007-2008 Elliot Shank.  All rights reserved.
index 1b471e2..3d584c3 100644 (file)
@@ -157,10 +157,11 @@ Returns a reference to an array of the collected exceptions.
 =item C<add_exception_or_rethrow( $eval_error )>
 
 If the parameter is an instance of
-L<Perl::Critic::Exception::Configuration> or
-L<Perl::Critic::Exception::AggregateConfiguration>, add it.
-Otherwise, C<die> with the parameter, if it is a reference, or
-C<confess> with it.  If the parameter is false, simply returns.
+L<Perl::Critic::Exception::Configuration|Perl::Critic::Exception::Configuration>
+or
+L<Perl::Critic::Exception::AggregateConfiguration|Perl::Critic::Exception::AggregateConfiguration>,
+add it.  Otherwise, C<die> with the parameter, if it is a reference,
+or C<confess> with it.  If the parameter is false, simply returns.
 
 
 =item C<has_exceptions()>
index 5ad78fb..d9ba4cc 100644 (file)
@@ -37,12 +37,12 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Configuration - A problem with L<Perl::Critic> configuration.
+Perl::Critic::Exception::Configuration - A problem with L<Perl::Critic|Perl::Critic> configuration.
 
 =head1 DESCRIPTION
 
 A representation of a problem found with the configuration of
-L<Perl::Critic>, whether from a F<.perlcriticrc>, another profile
+L<Perl::Critic|Perl::Critic>, whether from a F<.perlcriticrc>, another profile
 file, or command line.
 
 This is an abstract class.  It should never be instantiated.
@@ -62,8 +62,8 @@ Where the configuration information came from, if it could be determined.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Exception::Configuration::Generic>
-L<Perl::Critic::Exception::Configuration::Option>
+L<Perl::Critic::Exception::Configuration::Generic|Perl::Critic::Exception::Configuration::Generic>
+L<Perl::Critic::Exception::Configuration::Option|Perl::Critic::Exception::Configuration::Option>
 
 
 =head1 AUTHOR
index c8b0f4f..ab8a6c9 100644 (file)
@@ -44,12 +44,13 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Configuration::Generic - A problem with L<Perl::Critic> configuration that doesn't involve an option.
+Perl::Critic::Exception::Configuration::Generic - A problem with L<Perl::Critic|Perl::Critic> configuration that doesn't involve an option.
 
 =head1 DESCRIPTION
 
-A representation of a problem found with the configuration of L<Perl::Critic>,
-whether from a F<.perlcriticrc>, another profile file, or command line.
+A representation of a problem found with the configuration of
+L<Perl::Critic|Perl::Critic>, whether from a F<.perlcriticrc>, another
+profile file, or command line.
 
 This covers things like file reading and parsing errors.
 
index 56e4e4a..119d568 100644 (file)
@@ -64,13 +64,13 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Configuration::Option - A problem with an option in the L<Perl::Critic> configuration.
+Perl::Critic::Exception::Configuration::Option - A problem with an option in the L<Perl::Critic|Perl::Critic> configuration.
 
 =head1 DESCRIPTION
 
 A representation of a problem found with an option in the
-configuration of L<Perl::Critic>, whether from a F<.perlcriticrc>,
-another profile file, or command line.
+configuration of L<Perl::Critic|Perl::Critic>, whether from a
+F<.perlcriticrc>, another profile file, or command line.
 
 This is an abstract class.  It should never be instantiated.
 
@@ -114,8 +114,8 @@ implement it.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Exception::Configuration::Option::Global>
-L<Perl::Critic::Exception::Configuration::Option::Policy>
+L<Perl::Critic::Exception::Configuration::Option::Global|Perl::Critic::Exception::Configuration::Option::Global>
+L<Perl::Critic::Exception::Configuration::Option::Policy|Perl::Critic::Exception::Configuration::Option::Policy>
 
 
 =head1 AUTHOR
index 7824749..751ae89 100644 (file)
@@ -36,13 +36,13 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Configuration::Option::Global - A problem with L<Perl::Critic> global configuration.
+Perl::Critic::Exception::Configuration::Option::Global - A problem with L<Perl::Critic|Perl::Critic> global configuration.
 
 =head1 DESCRIPTION
 
 A representation of a problem found with the global configuration of
-L<Perl::Critic>, whether from a F<.perlcriticrc>, another profile
-file, or command line.
+L<Perl::Critic|Perl::Critic>, whether from a F<.perlcriticrc>, another
+profile file, or command line.
 
 This is an abstract class.  It should never be instantiated.
 
index 4d3eeba..ea7ba1e 100644 (file)
@@ -65,8 +65,8 @@ Perl::Critic::Exception::Configuration::Option::Global::ExtraParameter - The con
 =head1 DESCRIPTION
 
 A representation of the configuration attempting to specify a value
-for an option that L<Perl::Critic> doesn't have, whether from a
-F<.perlcriticrc>, another profile file, or command line.
+for an option that L<Perl::Critic|Perl::Critic> doesn't have, whether
+from a F<.perlcriticrc>, another profile file, or command line.
 
 
 =head1 CLASS METHODS
index a47e534..024b5bb 100644 (file)
@@ -56,8 +56,8 @@ Perl::Critic::Exception::Configuration::Option::Policy - A problem with configur
 =head1 DESCRIPTION
 
 A representation of a problem found with the configuration of a
-L<Perl::Critic::Policy>, whether from a F<.perlcriticrc>, another
-profile file, or command line.
+L<Perl::Critic::Policy|Perl::Critic::Policy>, whether from a
+F<.perlcriticrc>, another profile file, or command line.
 
 This is an abstract class.  It should never be instantiated.
 
index 54ca27b..500879e 100644 (file)
@@ -67,8 +67,9 @@ Perl::Critic::Exception::Configuration::Option::Policy::ExtraParameter - The con
 =head1 DESCRIPTION
 
 A representation of the configuration attempting to specify a value
-for a parameter that a L<Perl::Critic::Policy> doesn't have, whether
-from a F<.perlcriticrc>, another profile file, or command line.
+for a parameter that a L<Perl::Critic::Policy|Perl::Critic::Policy>
+doesn't have, whether from a F<.perlcriticrc>, another profile file,
+or command line.
 
 
 =head1 CLASS METHODS
index 9751523..7eaadc6 100644 (file)
@@ -74,9 +74,9 @@ Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue - A probl
 
 =head1 DESCRIPTION
 
-A representation of a problem found with the value of a parameter for a
-L<Perl::Critic::Policy>, whether from a F<.perlcriticrc>, another
-profile file, or command line.
+A representation of a problem found with the value of a parameter for
+a L<Perl::Critic::Policy|Perl::Critic::Policy>, whether from a
+F<.perlcriticrc>, another profile file, or command line.
 
 
 =head1 CLASS METHODS
index 2db3993..3f6444e 100644 (file)
@@ -63,7 +63,7 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Fatal - A problem that should cause L<Perl::Critic> to stop running.
+Perl::Critic::Exception::Fatal - A problem that should cause L<Perl::Critic|Perl::Critic> to stop running.
 
 =head1 DESCRIPTION
 
@@ -82,7 +82,8 @@ This is an abstract class.  It should never be instantiated.
 
 =item C<full_message()>
 
-Overrides L<Exception::Class/"full_message"> to include extra information.
+Overrides L<Exception::Class/"full_message"> to include extra
+information.
 
 
 =back
index 0fafd30..3e0a814 100644 (file)
@@ -44,11 +44,12 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Exception::Fatal::Internal - A problem with the L<Perl::Critic> implementation, i.e. a bug.
+Perl::Critic::Exception::Fatal::Internal - A problem with the L<Perl::Critic|Perl::Critic> implementation, i.e. a bug.
 
 =head1 DESCRIPTION
 
-A representation of a bug found in the code of L<Perl::Critic>.
+A representation of a bug found in the code of
+L<Perl::Critic|Perl::Critic>.
 
 
 =head1 METHODS
index 0743f9a..b5d19af 100644 (file)
@@ -183,11 +183,13 @@ __END__
 
 Perl::Critic::OptionsProcessor - The global configuration default values, combined with command-line values.
 
+
 =head1 DESCRIPTION
 
 This is a helper class that encapsulates the default parameters for
-constructing a L<Perl::Critic::Config> object.  There are no
-user-serviceable parts here.
+constructing a L<Perl::Critic::Config|Perl::Critic::Config> object.
+There are no user-serviceable parts here.
+
 
 =head1 CONSTRUCTOR
 
@@ -195,12 +197,13 @@ user-serviceable parts here.
 
 =item C< new( %DEFAULT_PARAMS ) >
 
-Returns a reference to a new C<Perl::Critic::OptionsProcessor> object.  You
-can override the coded defaults by passing in name-value pairs that
-correspond to the methods listed below.
+Returns a reference to a new C<Perl::Critic::OptionsProcessor> object.
+You can override the coded defaults by passing in name-value pairs
+that correspond to the methods listed below.
 
-This is usually only invoked by L<Perl::Critic::UserProfile>, which
-passes in the global values from a F<.perlcriticrc> file.  This object
+This is usually only invoked by
+L<Perl::Critic::UserProfile|Perl::Critic::UserProfile>, which passes
+in the global values from a F<.perlcriticrc> file.  This object
 contains no information for individual Policies.
 
 =back
@@ -212,65 +215,83 @@ contains no information for individual Policies.
 =item C< exclude() >
 
 Returns a reference to a list of the default exclusion patterns.  If
-there are no default exclusion patterns, then the list will be empty.
+onto by
+L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter>.  there
+are no default exclusion patterns, then the list will be empty.
+
 
 =item C< force() >
 
 Returns the default value of the C<force> flag (Either 1 or 0).
 
+
 =item C< include() >
 
 Returns a reference to a list of the default inclusion patterns.  If
 there are no default exclusion patterns, then the list will be empty.
 
+
 =item C< only() >
 
 Returns the default value of the C<only> flag (Either 1 or 0).
 
+
 =item C< profile_strictness() >
 
 Returns the default value of C<profile_strictness> as an unvalidated
 string.
 
+
 =item C< single_policy() >
 
 Returns the default C<single-policy> pattern.  (As a string.)
 
+
 =item C< severity() >
 
 Returns the default C<severity> setting. (1..5).
 
+
 =item C< theme() >
 
 Returns the default C<theme> setting. (As a string).
 
+
 =item C< top() >
 
 Returns the default C<top> setting. (Either 0 or a positive integer).
 
+
 =item C< verbose() >
 
 Returns the default C<verbose> setting. (Either a number or format
 string).
 
+
 =item C< color() >
 
 Returns the default C<color> setting. (Either 1 or 0).
 
+
 =item C< criticism_fatal() >
 
 Returns the default C<criticism-fatal> setting (Either 1 or 0).
 
+
 =back
 
+
 =head1 SEE ALSO
 
-L<Perl::Critic::Config>, L<Perl::Critic::UserProfile>
+L<Perl::Critic::Config|Perl::Critic::Config>,
+L<Perl::Critic::UserProfile|Perl::Critic::UserProfile>
+
 
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index 1d0741a..4e7d51f 100644 (file)
@@ -537,10 +537,11 @@ Perl::Critic::Policy - Base class for all Policy modules.
 Perl::Critic::Policy is the abstract base class for all Policy
 objects.  If you're developing your own Policies, your job is to
 implement and override its methods in a subclass.  To work with the
-L<Perl::Critic> engine, your implementation must behave as described
-below.  For a detailed explanation on how to make new Policy modules,
-please see the L<Perl::Critic::DEVELOPER> document included in this
-distribution.
+L<Perl::Critic|Perl::Critic> engine, your implementation must behave
+as described below.  For a detailed explanation on how to make new
+Policy modules, please see the
+L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> document included
+in this distribution.
 
 
 =head1 METHODS
@@ -551,11 +552,11 @@ distribution.
 
 Returns a reference to a new subclass of Perl::Critic::Policy. If your
 Policy requires any special arguments, they will be passed in here as
-key-value pairs.  Users of L<perlcritic> can specify these in their
-config file.  Unless you override the C<new> method, the default
-method simply returns a reference to an empty hash that has been
-blessed into your subclass.  However, you really should not override
-this; override C<initialize_if_enabled()> instead.
+key-value pairs.  Users of L<perlcritic|perlcritic> can specify these
+in their config file.  Unless you override the C<new> method, the
+default method simply returns a reference to an empty hash that has
+been blessed into your subclass.  However, you really should not
+override this; override C<initialize_if_enabled()> instead.
 
 This constructor is always called regardless of whether the user has
 enabled this Policy or not.
@@ -578,11 +579,13 @@ return C<$FALSE> if they are not.
 
 =item C< violates( $element, $document ) >
 
-Given a L<PPI::Element> and a L<PPI::Document>, returns one or more
-L<Perl::Critic::Violation> objects if the C<$element> violates this
-Policy.  If there are no violations, then it returns an empty list.
-If the Policy encounters an exception, then it should C<croak> with an
-error message and let the caller decide how to handle it.
+Given a L<PPI::Element|PPI::Element> and a
+L<PPI::Document|PPI::Document>, returns one or more
+L<Perl::Critic::Violation|Perl::Critic::Violation> objects if the
+C<$element> violates this Policy.  If there are no violations, then it
+returns an empty list.  If the Policy encounters an exception, then it
+should C<croak> with an error message and let the caller decide how to
+handle it.
 
 C<violates()> is an abstract method and it will abort if you attempt
 to invoke it directly.  It is the heart of all Policy modules, and
@@ -594,24 +597,25 @@ your subclass B<must> override this method.
 Returns a reference to a new C<Perl::Critic::Violation> object. The
 arguments are a description of the violation (as string), an
 explanation for the policy (as string) or a series of page numbers in
-PBP (as an ARRAY ref), a reference to the L<PPI> element that caused
-the violation.
+PBP (as an ARRAY ref), a reference to the L<PPI|PPI> element that
+caused the violation.
 
-These are the same as the constructor to L<Perl::Critic::Violation>,
-but without the severity.  The Policy itself knows the severity.
+These are the same as the constructor to
+L<Perl::Critic::Violation|Perl::Critic::Violation>, but without the
+severity.  The Policy itself knows the severity.
 
 
 =item C< new_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) >
 
 Create a
-L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
+L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
 for this Policy.
 
 
 =item C< throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) >
 
 Create and throw a
-L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>.
+L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>.
 Useful in parameter parser implementations.
 
 
@@ -658,13 +662,13 @@ document.
 =item C< default_severity() >
 
 Returns the default severity for violating this Policy.  See the
-C<$SEVERITY> constants in L<Perl::Critic::Utils> for an enumeration of
-possible severity values.  By default, this method returns
-C<$SEVERITY_LOWEST>.  Authors of Perl::Critic::Policy subclasses
-should override this method to return a value that they feel is
-appropriate for their Policy.  In general, Polices that are widely
-accepted or tend to prevent bugs should have a higher severity than
-those that are more subjective or cosmetic in nature.
+C<$SEVERITY> constants in L<Perl::Critic::Utils|Perl::Critic::Utils>
+for an enumeration of possible severity values.  By default, this
+method returns C<$SEVERITY_LOWEST>.  Authors of Perl::Critic::Policy
+subclasses should override this method to return a value that they
+feel is appropriate for their Policy.  In general, Polices that are
+widely accepted or tend to prevent bugs should have a higher severity
+than those that are more subjective or cosmetic in nature.
 
 
 =item C< get_severity() >
@@ -672,7 +676,8 @@ those that are more subjective or cosmetic in nature.
 Returns the severity of violating this Policy.  If the severity has
 not been explicitly defined by calling C<set_severity>, then the
 C<default_severity> is returned.  See the C<$SEVERITY> constants in
-L<Perl::Critic::Utils> for an enumeration of possible severity values.
+L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of
+possible severity values.
 
 
 =item C< set_severity( $N ) >
@@ -681,7 +686,8 @@ Sets the severity for violating this Policy.  Clients of
 Perl::Critic::Policy objects can call this method to assign a
 different severity to the Policy if they don't agree with the
 C<default_severity>.  See the C<$SEVERITY> constants in
-L<Perl::Critic::Utils> for an enumeration of possible values.
+L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of
+possible values.
 
 
 =item C< default_themes() >
@@ -732,7 +738,7 @@ Returns whether information about the parameters is available.
 =item C< get_parameters() >
 
 Returns a reference to an array containing instances of
-L<Perl::Critic::PolicyParameter>.
+L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter>.
 
 Note that this will return an empty list if the parameters for this
 policy are unknown.  In order to differentiate between this
@@ -742,7 +748,9 @@ parameters, it is necessary to call C<parameter_metadata_available()>.
 
 =item C< get_parameter( $parameter_name ) >
 
-Returns the L<Perl::Critic::PolicyParameter> with the specified name.
+Returns the
+L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> with
+the specified name.
 
 
 =item C<set_format( $FORMAT )>
@@ -770,11 +778,12 @@ variable.  See L<"OVERLOADS"> for the details.
 
 =head1 DOCUMENTATION
 
-When your Policy module first C<use>s L<Perl::Critic::Violation>, it
-will try and extract the DESCRIPTION section of your Policy module's
-POD.  This information is displayed by Perl::Critic if the verbosity
-level is set accordingly.  Therefore, please include a DESCRIPTION
-section in the POD for any Policy modules that you author.  Thanks.
+When your Policy module first C<use>s
+L<Perl::Critic::Violation|Perl::Critic::Violation>, it will try and
+extract the DESCRIPTION section of your Policy module's POD.  This
+information is displayed by Perl::Critic if the verbosity level is set
+accordingly.  Therefore, please include a DESCRIPTION section in the
+POD for any Policy modules that you author.  Thanks.
 
 
 =head1 OVERLOADS
@@ -785,7 +794,8 @@ on the current value of the C<$FORMAT> package variable.
 
 Formats are a combination of literal and escape characters similar to
 the way C<sprintf> works.  If you want to know the specific formatting
-capabilities, look at L<String::Format>. Valid escape characters are:
+capabilities, look at L<String::Format|String::Format>. Valid escape
+characters are:
 
 
 =over
index 0beb95f..ae8168f 100644 (file)
@@ -97,23 +97,26 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitBooleanGrep - Use C<List::MoreUtils::any> instead of C<grep> in boolean context.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Using C<grep> in boolean context is a common idiom for checking if any
-elements in a list match a condition.  This works because boolean context is a
-subset of scalar context, and grep returns the number of matches in scalar
-context.  A non-zero number of matches means a match.
+elements in a list match a condition.  This works because boolean
+context is a subset of scalar context, and grep returns the number of
+matches in scalar context.  A non-zero number of matches means a
+match.
 
-But consider the case of a long array where the first element is a match.
-Boolean C<grep> still checks all of the rest of the elements needlessly.
-Instead, a better solution is to use the C<any> function from
-L<List::MoreUtils>, which short-circuits after the first successful match to
-save time.
+But consider the case of a long array where the first element is a
+match.  Boolean C<grep> still checks all of the rest of the elements
+needlessly.  Instead, a better solution is to use the C<any> function
+from L<List::MoreUtils|List::MoreUtils>, which short-circuits after
+the first successful match to save time.
 
 
 =head1 CONFIGURATION
@@ -123,18 +126,21 @@ This Policy is not configurable except for the standard options.
 
 =head1 CAVEATS
 
-The algorithm for detecting boolean context takes a LOT of shortcuts.  There
-are lots of known false negatives.  But, I was conservative in writing this,
-so I hope there are no false positives.
+The algorithm for detecting boolean context takes a LOT of shortcuts.
+There are lots of known false negatives.  But, I was conservative in
+writing this, so I hope there are no false positives.
+
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl
-Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
+
 
 =head1 COPYRIGHT
 
index 4b298ba..a6f7083 100644 (file)
@@ -84,9 +84,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitComplexMappings - Map blocks should have a single statement.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -102,13 +104,15 @@ The best solutions to a complex mapping are: 1) write a subroutine
 that performs the manipulation and call that from map; 2) rewrite the
 map as a for loop.
 
+
 =head1 CAVEATS
 
 This policy currently misses some compound statements inside of the
 map.  For example, the following code incorrectly does not trigger a
 violation:
 
-  map { do { foo(); bar() } } @list
+    map { do { foo(); bar() } } @list
+
 
 =head1 CONFIGURATION
 
@@ -116,16 +120,20 @@ By default this policy flags any mappings with more than one
 statement.  While we do not recommend it, you can increase this limit
 as follows in a F<.perlcriticrc> file:
 
-  [BuiltinFunctions::ProhibitComplexMappings]
-  max_statements = 2
+    [BuiltinFunctions::ProhibitComplexMappings]
+    max_statements = 2
+
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
+
 
 =head1 COPYRIGHT
 
index bed02fb..af840b7 100644 (file)
@@ -58,18 +58,21 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr - Use 4-argument C<substr> instead of writing C<substr($foo, 2, 6) = $bar>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Conway discourages the use of C<substr()> as an lvalue, instead
-recommending that the 4-argument version of C<substr()> be used instead.
+recommending that the 4-argument version of C<substr()> be used
+instead.
 
-  substr($something, 1, 2) = $newvalue;     # not ok
-  substr($something, 1, 2, $newvalue);      # ok
+    substr($something, 1, 2) = $newvalue;     # not ok
+    substr($something, 1, 2, $newvalue);      # ok
 
 
 =head1 CONFIGURATION
@@ -81,6 +84,7 @@ This Policy is not configurable except for the standard options.
 
 Graham TerMarsch <graham@howlingfrog.com>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2005-2007 Graham TerMarsch.  All rights reserved.
index d1077d4..7b476ec 100644 (file)
@@ -87,24 +87,26 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitReverseSortBlock - Forbid $b before $a in sort blocks.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-Conway says that it is much clearer to use C<reverse> than to flip C<$a> and
-C<$b> around in a C<sort> block.  He also suggests that, in newer perls,
-C<reverse> is specifically looked for and optimized, and in the case of a
-simple reversed string C<sort>, using C<reverse> with a C<sort> with no block
-is faster even in old perls.
+Conway says that it is much clearer to use C<reverse> than to flip
+C<$a> and C<$b> around in a C<sort> block.  He also suggests that, in
+newer perls, C<reverse> is specifically looked for and optimized, and
+in the case of a simple reversed string C<sort>, using C<reverse> with
+a C<sort> with no block is faster even in old perls.
 
-  my @foo = sort { $b cmp $a } @bar;         #not ok
-  my @foo = reverse sort @bar;               #ok
+    my @foo = sort { $b cmp $a } @bar;         #not ok
+    my @foo = reverse sort @bar;               #ok
 
-  my @foo = sort { $b <=> $a } @bar;         #not ok
-  my @foo = reverse sort { $a <=> $b } @bar; #ok
+    my @foo = sort { $b <=> $a } @bar;         #not ok
+    my @foo = reverse sort { $a <=> $b } @bar; #ok
 
 
 =head1 CONFIGURATION
@@ -116,6 +118,7 @@ This Policy is not configurable except for the standard options.
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2006 Chris Dolan.  All rights reserved.
index 24778fe..33844db 100644 (file)
@@ -62,25 +62,27 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect - Use L<Time::HiRes> instead of something like C<select(undef, undef, undef, .05)>.
+Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect - Use L<Time::HiRes|Time::HiRes> instead of something like C<select(undef, undef, undef, .05)>.
+
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Conway discourages the use of C<select()> for performing non-integer
-sleeps.  Although documented in L<perlfunc>, it's something that
-generally requires the reader to read C<perldoc -f select> to figure
-out what it should be doing.  Instead, Conway recommends that you use
-the C<Time::HiRes> module when you want to sleep.
+sleeps.  Although documented in L<perlfunc|perlfunc>, it's something
+that generally requires the reader to read C<perldoc -f select> to
+figure out what it should be doing.  Instead, Conway recommends that
+you use the C<Time::HiRes> module when you want to sleep.
 
-  select undef, undef, undef, 0.25;         # not ok
+    select undef, undef, undef, 0.25;         # not ok
 
-  use Time::HiRes;
-  sleep( 0.25 );                            # ok
+    use Time::HiRes;
+    sleep( 0.25 );                            # ok
 
 
 =head1 CONFIGURATION
@@ -90,12 +92,14 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Time::HiRes>.
+L<Time::HiRes|Time::HiRes>.
+
 
 =head1 AUTHOR
 
 Graham TerMarsch <graham@howlingfrog.com>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2005-2007 Graham TerMarsch.  All rights reserved.
index cdc234b..d2b7fe5 100644 (file)
@@ -56,9 +56,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval - Write C<eval { my $foo; bar($foo) }> instead of C<eval "my $foo; bar($foo);">.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -78,14 +80,16 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep>
+L<Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep|Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep>
+
+L<Perl::Critic::Policy::ControlStrucutres::RequireBlockMap|Perl::Critic::Policy::ControlStrucutres::RequireBlockMap>
 
-L<Perl::Critic::Policy::ControlStrucutres::RequireBlockMap>
 
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index b649469..bd2a43d 100644 (file)
@@ -60,9 +60,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitStringySplit - Write C<split /-/, $string> instead of C<split '-', $string>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -72,9 +74,9 @@ regular expression, even if you specify it as a string.  This causes
 much confusion if the string contains regex metacharacters.  So for
 clarity, always express the PATTERN argument as a regex.
 
-  $string = 'Fred|Barney';
-  @names = split '|', $string; #not ok, is ('F', 'r', 'e', 'd', '|', 'B', 'a' ...)
-  @names = split m/[|]/, $string; #ok, is ('Fred', Barney')
+    $string = 'Fred|Barney';
+    @names = split '|', $string; #not ok, is ('F', 'r', 'e', 'd', '|', 'B', 'a' ...)
+    @names = split m/[|]/, $string; #ok, is ('Fred', Barney')
 
 When the PATTERN is a single space the C<split> function has special
 behavior, so Perl::Critic forgives that usage.  See C<"perldoc -f
@@ -88,14 +90,16 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep>
+L<Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep|Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep>
+
+L<Perl::Critic::Policy::ControlStrucutres::RequireBlockMap|Perl::Critic::Policy::ControlStrucutres::RequireBlockMap>
 
-L<Perl::Critic::Policy::ControlStrucutres::RequireBlockMap>
 
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index a9aca55..4360cca 100644 (file)
@@ -52,15 +52,17 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan - Write C<< eval { $foo->can($name) } >> instead of C<UNIVERSAL::can($foo, $name)>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-  print UNIVERSAL::can($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
-  print eval { $obj->can('Foo::Bar') } ? 'yes' : 'no';    #ok
+    print UNIVERSAL::can($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
+    print eval { $obj->can('Foo::Bar') } ? 'yes' : 'no';    #ok
 
 As of Perl 5.9.3, the use of UNIVERSAL::can as a function has been
 deprecated and the method form is preferred instead.  Formerly, the
@@ -70,8 +72,8 @@ functional form makes it impossible for packages to override C<can()>,
 a technique which is crucial for implementing mock objects and some
 facades.
 
-See the CPAN module L<UNIVERSAL::can> for a more thorough discussion
-of this topic.
+See L<UNIVERSAL::can|UNIVERSAL::can> for a more thorough discussion of
+this topic.
 
 
 =head1 CONFIGURATION
@@ -81,12 +83,14 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa>
+L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa|Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa>
+
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2006-2008 Chris Dolan.  All rights reserved.
index b830a67..71f7fcc 100644 (file)
@@ -52,15 +52,17 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa - Write C<< eval { $foo->isa($pkg) } >> instead of C<UNIVERSAL::isa($foo, $pkg)>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-  print UNIVERSAL::isa($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
-  print eval { $obj->isa('Foo::Bar') } ? 'yes' : 'no';    #ok
+    print UNIVERSAL::isa($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
+    print eval { $obj->isa('Foo::Bar') } ? 'yes' : 'no';    #ok
 
 As of Perl 5.9.3, the use of C<UNIVERSAL::isa> as a function has been
 deprecated and the method form is preferred instead.  Formerly, the
@@ -73,8 +75,8 @@ facades.
 Another alternative to UNIVERSAL::isa is the C<_INSTANCE> method of
 Param::Util, which is faster.
 
-See the CPAN module L<UNIVERSAL::isa> for an incendiary discussion of
-this topic.
+See the CPAN module L<UNIVERSAL::isa|UNIVERSAL::isa> for an incendiary
+discussion of this topic.
 
 
 =head1 CONFIGURATION
@@ -84,7 +86,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan>
+L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan|Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan>
 
 =head1 AUTHOR
 
index 1a1767b..b43ab6e 100644 (file)
@@ -54,9 +54,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitVoidGrep - Don't use C<grep> in void contexts.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -65,14 +67,14 @@ C<map> and C<grep> are intended to be pure functions, not mutators.
 If you want to iterate with side-effects, then you should use a proper
 C<for> or C<foreach> loop.
 
-  grep{ print frobulate($_) } @list;           #not ok
-  print map{ frobulate($_) } @list;            #ok
+    grep{ print frobulate($_) } @list;           #not ok
+    print map{ frobulate($_) } @list;            #ok
 
-  grep{ $_ = lc $_ } @list;                    #not ok
-  for( @list ){ $_ = lc $_  };                 #ok
+    grep{ $_ = lc $_ } @list;                    #not ok
+    for( @list ){ $_ = lc $_  };                 #ok
 
-  map{ push @frobbed, frobulate($_) } @list;   #not ok
-  @frobbed = map { frobulate($_) } @list;      #ok
+    map{ push @frobbed, frobulate($_) } @list;   #not ok
+    @frobbed = map { frobulate($_) } @list;      #ok
 
 
 =head1 CONFIGURATION
@@ -84,6 +86,7 @@ This Policy is not configurable except for the standard options.
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index ab1bf9d..5b192ba 100644 (file)
@@ -54,9 +54,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::ProhibitVoidMap - Don't use C<map> in void contexts.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -65,14 +67,14 @@ C<map> and C<grep> are intended to be pure functions, not mutators.
 If you want to iterate with side-effects, then you should use a proper
 C<for> or C<foreach> loop.
 
-  grep{ print frobulate($_) } @list;           #not ok
-  print map{ frobulate($_) } @list;            #ok
+    grep{ print frobulate($_) } @list;           #not ok
+    print map{ frobulate($_) } @list;            #ok
 
-  grep{ $_ = lc $_ } @list;                    #not ok
-  for( @list ){ $_ = lc $_  };                 #ok
+    grep{ $_ = lc $_ } @list;                    #not ok
+    for( @list ){ $_ = lc $_  };                 #ok
 
-  map{ push @frobbed, frobulate($_) } @list;   #not ok
-  @frobbed = map { frobulate($_) } @list;      #ok
+    map{ push @frobbed, frobulate($_) } @list;   #not ok
+    @frobbed = map { frobulate($_) } @list;      #ok
 
 
 =head1 CONFIGURATION
@@ -84,6 +86,7 @@ This Policy is not configurable except for the standard options.
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index 7278344..fc7cad3 100644 (file)
@@ -62,19 +62,20 @@ Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep - Write C<grep { $_ =~
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-The expression forms of C<grep> and C<map> are awkward and hard to read.
-Use the block forms instead.
+The expression forms of C<grep> and C<map> are awkward and hard to
+read.  Use the block forms instead.
 
-  @matches = grep  /pattern/,    @list;        #not ok
-  @matches = grep { /pattern/ }  @list;        #ok
+    @matches = grep  /pattern/,    @list;        #not ok
+    @matches = grep { /pattern/ }  @list;        #ok
 
-  @mapped = map  transform($_),    @list;      #not ok
-  @mapped = map { transform($_) }  @list;      #ok
+    @mapped = map  transform($_),    @list;      #not ok
+    @mapped = map { transform($_) }  @list;      #ok
 
 
 
@@ -85,9 +86,9 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval>
+L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval|Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval>
 
-L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap>
+L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap|Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap>
 
 =head1 AUTHOR
 
index 1a36f9b..c1aef64 100644 (file)
@@ -56,21 +56,23 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap - Write C<map { $_ =~ /$pattern/ } @list> instead of C<map /$pattern/, @list>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-The expression forms of C<grep> and C<map> are awkward and hard to read.
-Use the block forms instead.
+The expression forms of C<grep> and C<map> are awkward and hard to
+read.  Use the block forms instead.
 
-  @matches = grep   /pattern/,   @list;        #not ok
-  @matches = grep { /pattern/ }  @list;        #ok
+    @matches = grep   /pattern/,   @list;        #not ok
+    @matches = grep { /pattern/ }  @list;        #ok
 
-  @mapped = map   transform($_),   @list;      #not ok
-  @mapped = map { transform($_) }  @list;      #ok
+    @mapped = map   transform($_),   @list;      #not ok
+    @mapped = map { transform($_) }  @list;      #ok
 
 
 
@@ -81,14 +83,16 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval>
+L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval|Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval>
+
+L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep|Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep>
 
-L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep>
 
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index a8e2d27..273d391 100644 (file)
@@ -53,9 +53,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction - Use C<glob q{*}> instead of <*>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -65,8 +67,8 @@ it is easily confused with the angle bracket file input operator.
 Instead, he recommends the use of the C<glob()> function as it makes
 it much more obvious what you're attempting to do.
 
-  @files = <*.pl>;              # not ok
-  @files = glob( "*.pl" );      # ok
+    @files = <*.pl>;              # not ok
+    @files = glob( "*.pl" );      # ok
 
 
 =head1 CONFIGURATION
@@ -78,6 +80,7 @@ This Policy is not configurable except for the standard options.
 
 Graham TerMarsch <graham@howlingfrog.com>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2005-2007 Graham TerMarsch.  All rights reserved.
index ac4f455..26e527b 100644 (file)
@@ -69,9 +69,11 @@ __END__
 
 Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock - Sort blocks should have a single statement.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
index 4c17012..b778d37 100644 (file)
@@ -52,9 +52,11 @@ __END__
 
 Perl::Critic::Policy::ClassHierarchies::ProhibitAutoloading - AUTOLOAD methods should be avoided.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -78,6 +80,7 @@ This Policy is not configurable except for the standard options.
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2006 Jeffrey Ryan Thalhammer.  All rights reserved.
index 2a7c436..e943eb3 100644 (file)
@@ -52,9 +52,11 @@ __END__
 
 Perl::Critic::Policy::ClassHierarchies::ProhibitExplicitISA - Employ C<use base> instead of C<@ISA>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -74,6 +76,7 @@ This Policy is not configurable except for the standard options.
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2006 Chris Dolan.  All rights reserved.
index 107ad72..92028fa 100644 (file)
@@ -55,9 +55,11 @@ __END__
 
 Perl::Critic::Policy::ClassHierarchies::ProhibitOneArgBless - Write C<bless {}, $class;> instead of just C<bless {};>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -65,12 +67,12 @@ This Policy is part of the core L<Perl::Critic> distribution.
 Always use the two-argument form of C<bless> because it allows
 subclasses to inherit your constructor.
 
-  sub new {
-      my $class = shift;
-      my $self = bless {};          # not ok
-      my $self = bless {}, $class;  # ok
-      return $self;
-  }
+    sub new {
+        my $class = shift;
+        my $self = bless {};          # not ok
+        my $self = bless {}, $class;  # ok
+        return $self;
+    }
 
 
 =head1 CONFIGURATION
index 5b33dfb..4858479 100644 (file)
@@ -75,9 +75,11 @@ __END__
 
 Perl::Critic::Policy::CodeLayout::ProhibitHardTabs - Use spaces instead of tabs.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -87,13 +89,14 @@ things you can do to your co-workers and colleagues, especially if
 those tabs are anywhere other than a leading position.  Because
 various applications and devices represent tabs differently, they can
 cause you code to look vastly different to other people.  Any decent
-editor can be configured to expand tabs into spaces.  L<Perl::Tidy>
-also does this for you.
+editor can be configured to expand tabs into spaces.
+L<Perl::Tidy|Perl::Tidy> also does this for you.
 
 This Policy catches all tabs in your source code, including POD,
 quotes, and HEREDOCs.  The contents of the C<__DATA__> section are not
 examined.
 
+
 =head1 CONFIGURATION
 
 Tabs in a leading position are allowed, but if you want to forbid all tabs
@@ -102,16 +105,19 @@ everywhere, put this to your F<.perlcriticrc> file:
     [CodeLayout::ProhibitHardTabs]
     allow_leading_tabs = 0
 
+
 =head1 NOTES
 
 Beware that Perl::Critic may report the location of the string that
 contains the tab, not the actual location of the tab, so you may need
 to do some hunting.  I'll try and fix this in the future.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index 47d79c5..5158e90 100644 (file)
@@ -177,9 +177,11 @@ __END__
 
 Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins - Write C<open $handle, $path> instead of C<open($handle, $path)>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -190,11 +192,11 @@ disambiguates built-in functions from user functions.  Exceptions are
 made for C<my>, C<local>, and C<our> which require parentheses when
 called with multiple arguments.
 
-  open($handle, '>', $filename); #not ok
-  open $handle, '>', $filename;  #ok
+    open($handle, '>', $filename); #not ok
+    open $handle, '>', $filename;  #ok
 
-  split(/$pattern/, @list); #not ok
-  split /$pattern/, @list;  #ok
+    split(/$pattern/, @list); #not ok
+    split /$pattern/, @list;  #ok
 
 
 =head1 CONFIGURATION
@@ -213,10 +215,12 @@ necessary to enforce precedence, but they cause still violations.  In
 those cases, consider using the '## no critic' comments to silence
 Perl::Critic.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index a8ed226..1538e99 100644 (file)
@@ -95,35 +95,39 @@ __END__
 
 Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists - Write C<qw(foo bar baz)> instead of C<('foo', 'bar', 'baz')>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Conway doesn't mention this, but I think C<qw()> is an underused
 feature of Perl.  Whenever you need to declare a list of one-word
-literals, the C<qw()> operator is wonderfully concise, and makes
-it easy to add to the list in the future.
+literals, the C<qw()> operator is wonderfully concise, and makes it
+easy to add to the list in the future.
+
+    @list = ('foo', 'bar', 'baz');  #not ok
+    @list = qw(foo bar baz);        #ok
 
-  @list = ('foo', 'bar', 'baz');  #not ok
-  @list = qw(foo bar baz);        #ok
 
 =head1 CONFIGURATION
 
 This policy can be configured to only pay attention to word lists with
-at least a particular number of elements.  By default, this value is 2,
-which means that lists containing zero or one elements are ignored.
+at least a particular number of elements.  By default, this value is
+2, which means that lists containing zero or one elements are ignored.
 The minimum list size to be looked at can be specified by giving a
 value for C<min_elements> in F<.perlcriticrc> like this:
 
-  [CodeLayout::ProhibitQuotedWordLists]
-  min_elements = 4
+    [CodeLayout::ProhibitQuotedWordLists]
+    min_elements = 4
 
 This would cause this policy to only complain about lists containing
 four or more words.
 
+
 =head1 NOTES
 
 In the PPI parlance, a "list" is almost anything with parentheses.
@@ -131,6 +135,7 @@ I've tried to make this Policy smart by targeting only "lists" that
 could be sensibly expressed with C<qw()>.  However, there may be some
 edge cases that I haven't covered.  If you find one, send me a note.
 
+
 =head1 IMPORTANT CHANGES
 
 This policy was formerly called C<RequireQuotedWords> which seemed a
@@ -143,10 +148,11 @@ to C<ProhibitQuotedWordLists> in your F<.perlcriticrc> file.
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
-Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 
 =head1 COPYRIGHT
 
+Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
+
 This program is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.  The full text of this license
 can be found in the LICENSE file included with this module.
index 48dce78..8fa2039 100644 (file)
@@ -105,9 +105,11 @@ __END__
 
 Perl::Critic::Policy::CodeLayout::ProhibitTrailingWhitespace - Don't use whitespace at the end of lines.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
index c44c15e..342a230 100644 (file)
@@ -80,9 +80,17 @@ __END__
 Perl::Critic::Policy::CodeLayout::RequireConsistentNewlines - Use the same newline through the source.
 
 
-=head1 CONFIGURATION
+=head1 AFFILIATION
 
-This Policy is not configurable except for the standard options.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
+
+
+=head1 DESCRIPTION
+
+Source code files are divided into lines with line endings of C<\r>,
+C<\n> or C<\r\n>.  Mixing these different line endings causes problems
+in many text editors and, notably, Module::Signature and GnuPG.
 
 
 =head1 CAVEAT
@@ -91,21 +99,17 @@ This policy works outside of PPI because PPI automatically normalizes
 source code to local newline conventions.  So, this will only work if
 we know the filename of the source code.
 
-=head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+=head1 CONFIGURATION
 
+This Policy is not configurable except for the standard options.
 
-=head1 DESCRIPTION
-
-Source code files are divided into lines with line endings of C<\r>,
-C<\n> or C<\r\n>.  Mixing these different line endings causes problems
-in many text editors and, notably, Module::Signature and GnuPG.
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2006 Chris Dolan.  All rights reserved.
index b139eb4..1b8674e 100644 (file)
@@ -126,11 +126,13 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Policy::CodeLayout::RequireTidyCode - Must run code through L<perltidy>.
+Perl::Critic::Policy::CodeLayout::RequireTidyCode - Must run code through L<perltidy|perltidy>.
+
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -138,41 +140,48 @@ This Policy is part of the core L<Perl::Critic> distribution.
 Conway does make specific recommendations for whitespace and
 curly-braces in your code, but the most important thing is to adopt a
 consistent layout, regardless of the specifics.  And the easiest way
-to do that is to use L<Perl::Tidy>.  This policy will complain if
-you're code hasn't been run through Perl::Tidy.
+to do that is to use L<Perl::Tidy|Perl::Tidy>.  This policy will
+complain if you're code hasn't been run through Perl::Tidy.
+
 
 =head1 CONFIGURATION
 
 This policy can be configured to tell Perl::Tidy to use a particular
-F<perltidyrc> file or no configuration at all.  By default, Perl::Tidy is told
-to look in its default location for configuration.  Perl::Critic can be told to
-tell Perl::Tidy to use a specific configuration file by putting an entry in a
-F<.perlcriticrc> file like this:
+F<perltidyrc> file or no configuration at all.  By default, Perl::Tidy
+is told to look in its default location for configuration.
+Perl::Critic can be told to tell Perl::Tidy to use a specific
+configuration file by putting an entry in a F<.perlcriticrc> file like
+this:
 
-  [CodeLayout::RequireTidyCode]
-  perltidyrc = /usr/share/perltidy.conf
+    [CodeLayout::RequireTidyCode]
+    perltidyrc = /usr/share/perltidy.conf
 
 As a special case, setting C<perltidyrc> to the empty string tells
 Perl::Tidy not to load any configuration file at all and just use
 Perl::Tidy's own default style.
 
-  [CodeLayout::RequireTidyCode]
-  perltidyrc =
+    [CodeLayout::RequireTidyCode]
+    perltidyrc =
+
 
 =head1 NOTES
 
-L<Perl::Tidy> is not included in the Perl::Critic distribution.  The
-latest version of Perl::Tidy can be downloaded from CPAN.  If
-Perl::Tidy is not installed, this policy is silently ignored.
+L<Perl::Tidy|Perl::Tidy> is not included in the Perl::Critic
+distribution.  The latest version of Perl::Tidy can be downloaded from
+CPAN.  If Perl::Tidy is not installed, this policy is silently
+ignored.
+
 
 =head1 SEE ALSO
 
-L<Perl::Tidy>
+L<Perl::Tidy|Perl::Tidy>
+
 
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index fff8eab..2f43430 100644 (file)
@@ -69,9 +69,11 @@ __END__
 
 Perl::Critic::Policy::CodeLayout::RequireTrailingCommas - Put a comma at the end of every multi-line list declaration, including the last one.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -80,13 +82,13 @@ Conway suggests that all elements in a multi-line list should be
 separated by commas, including the last element.  This makes it a
 little easier to re-order the list by cutting and pasting.
 
-  my @list = ($foo,
-              $bar,
-              $baz);  #not ok
+    my @list = ($foo,
+                $bar,
+                $baz);  #not ok
 
-  my @list = ($foo,
-              $bar,
-              $baz,); #ok
+    my @list = ($foo,
+                $bar,
+                $baz,); #ok
 
 
 =head1 CONFIGURATION
@@ -102,10 +104,12 @@ have at least one element and are being assigned to something.
 However, there may be some edge cases that I haven't covered.  If you
 find one, send me a note.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index 88104bd..f12b78b 100644 (file)
@@ -62,22 +62,23 @@ Perl::Critic::Policy::ControlStructures::ProhibitCStyleForLoops - Write C<for(0.
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-The 3-part C<for> loop that Perl inherits from C is butt-ugly, and only
-really necessary if you need irregular counting.  The very Perlish
-C<..> operator is much more elegant and readable.
+The 3-part C<for> loop that Perl inherits from C is butt-ugly, and
+only really necessary if you need irregular counting.  The very
+Perlish C<..> operator is much more elegant and readable.
 
-  for($i=0; $i<=$max; $i++){      #ick!
-      do_something($i);
-  }
+    for($i=0; $i<=$max; $i++){      #ick!
+        do_something($i);
+    }
 
-  for(0..$max){                   #very nice
-    do_something($_);
-  }
+    for(0..$max){                   #very nice
+        do_something($_);
+    }
 
 
 =head1 CONFIGURATION
index e5a9d0f..f1f8cbd 100644 (file)
@@ -10,6 +10,7 @@ package Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse;
 use 5.006001;
 use strict;
 use warnings;
+
 use Readonly;
 
 use Perl::Critic::Utils qw{ :severities };
@@ -75,39 +76,40 @@ Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse - Don't write l
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Long C<if-elsif> chains are hard to digest, especially if they are
 longer than a single page or screen.  If testing for equality, use a
-hash lookup instead.  See L<Switch> for another approach.
-
-  if ($condition1) {         #ok
-      $foo = 1;
-  }
-  elsif ($condition2) {      #ok
-      $foo = 2;
-  }
-  elsif ($condition3) {      #ok
-      $foo = 3;
-  }
-  elsif ($condition4) {      #too many!
-      $foo = 4;
-  }
-  else {                     #ok
-      $foo = $default;
-  }
+hash lookup instead.  See L<Switch|Switch> for another approach.
+
+    if ($condition1) {         #ok
+        $foo = 1;
+    }
+    elsif ($condition2) {      #ok
+        $foo = 2;
+    }
+    elsif ($condition3) {      #ok
+        $foo = 3;
+    }
+    elsif ($condition4) {      #too many!
+        $foo = 4;
+    }
+    else {                     #ok
+        $foo = $default;
+    }
 
 =head1 CONFIGURATION
 
-This policy can be configured with a maximum number of C<elsif> alternatives
-to allow.  The default is 2.  This can be specified via a C<max_elsif> item in
-the F<.perlcriticrc> file:
+This policy can be configured with a maximum number of C<elsif>
+alternatives to allow.  The default is 2.  This can be specified via a
+C<max_elsif> item in the F<.perlcriticrc> file:
 
- [ControlStructures::ProhibitCascadingIfElse]
- max_elsif = 3
   [ControlStructures::ProhibitCascadingIfElse]
   max_elsif = 3
 
 =head1 AUTHOR
 
index d041ad8..6ff7365 100644 (file)
@@ -78,7 +78,8 @@ Perl::Critic::Policy::ControlStructures::ProhibitDeepNests - Don't write deeply
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -91,14 +92,14 @@ Design of Existing Code".
 
 =head1 CONFIGURATION
 
-The maximum number of nested control structures can be configured via a value
-for C<max_nests> in a F<.perlcriticrc> file.  Each for-loop, if-else, while,
-and until block is counted as one nest.  Postfix forms of these constructs are
-not counted.  The default maximum is 5.  Customization in a F<.perlcriticrc>
-file looks like this:
+The maximum number of nested control structures can be configured via
+a value for C<max_nests> in a F<.perlcriticrc> file.  Each for-loop,
+if-else, while, and until block is counted as one nest.  Postfix forms
+of these constructs are not counted.  The default maximum is 5.
+Customization in a F<.perlcriticrc> file looks like this:
 
- [ControlStructures::ProhibitDeepNests]
- max_nests = 3
   [ControlStructures::ProhibitDeepNests]
   max_nests = 3
 
 =head1 AUTHOR
 
index 2290904..bb55bd3 100644 (file)
@@ -65,7 +65,8 @@ Perl::Critic::Policy::ControlStructures::ProhibitLabelsWithSpecialBlockNames - D
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
index f723f31..441cc2d 100644 (file)
@@ -231,57 +231,61 @@ Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions - Don't m
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-C<map>, C<grep> and other list operators are intended to transform arrays into
-other arrays by applying code to the array elements one by one.  For speed,
-the elements are referenced via a C<$_> alias rather than copying them.  As a
-consequence, if the code block of the C<map> or C<grep> modify C<$_> in any
-way, then it is actually modifying the source array.  This IS technically
-allowed, but those side effects can be quite surprising, especially when the
-array being passed is C<@_> or perhaps C<values(%ENV)>!  Instead authors
-should restrict in-place array modification to C<for(@array) { ... }>
-constructs instead, or use C<List::MoreUtils::apply()>.
+C<map>, C<grep> and other list operators are intended to transform
+arrays into other arrays by applying code to the array elements one by
+one.  For speed, the elements are referenced via a C<$_> alias rather
+than copying them.  As a consequence, if the code block of the C<map>
+or C<grep> modify C<$_> in any way, then it is actually modifying the
+source array.  This IS technically allowed, but those side effects can
+be quite surprising, especially when the array being passed is C<@_>
+or perhaps C<values(%ENV)>!  Instead authors should restrict in-place
+array modification to C<for(@array) { ... }> constructs instead, or
+use C<List::MoreUtils::apply()>.
 
 =head1 CONFIGURATION
 
 By default, this policy applies to the following list functions:
 
-  map grep
-  List::Util qw(first)
-  List::MoreUtils qw(any all none notall true false firstidx first_index
-                     lastidx last_index insert_after insert_after_string)
+    map grep
+    List::Util qw(first)
+    List::MoreUtils qw(any all none notall true false firstidx
+                       first_index lastidx last_index insert_after
+                       insert_after_string)
 
 This list can be overridden the F<.perlcriticrc> file like this:
 
- [ControlStructures::ProhibitMutatingListFunctions]
- list_funcs = map grep List::Util::first
   [ControlStructures::ProhibitMutatingListFunctions]
   list_funcs = map grep List::Util::first
 
 Or, one can just append to the list like so:
 
- [ControlStructures::ProhibitMutatingListFunctions]
- add_list_funcs = Foo::Bar::listmunge
   [ControlStructures::ProhibitMutatingListFunctions]
   add_list_funcs = Foo::Bar::listmunge
 
 =head1 LIMITATIONS
 
 This policy deliberately does not apply to C<for (@array) { ... }> or
 C<List::MoreUtils::apply()>.
 
-Currently, the policy only detects explicit external module usage like this:
+Currently, the policy only detects explicit external module usage like
+this:
 
-  my @out = List::MoreUtils::any {s/^foo//} @in;
+    my @out = List::MoreUtils::any {s/^foo//} @in;
 
 and not like this:
 
-  use List::MoreUtils qw(any);
-  my @out = any {s/^foo//} @in;
+    use List::MoreUtils qw(any);
+    my @out = any {s/^foo//} @in;
 
-This policy looks only for modifications of C<$_>.  Other naughtiness could
-include modifying C<$a> and C<$b> in C<sort> and the like.  That's beyond the
-scope of this policy.
+This policy looks only for modifications of C<$_>.  Other naughtiness
+could include modifying C<$a> and C<$b> in C<sort> and the like.
+That's beyond the scope of this policy.
 
 =head1 AUTHOR
 
index 4fb6dca..2099257 100644 (file)
@@ -148,18 +148,19 @@ Perl::Critic::Policy::ControlStructures::ProhibitNegativeExpressionsInUnlessAndU
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-  until ($foo ne 'blah') {          #not ok
-      ...
-  }
+    until ($foo ne 'blah') {          #not ok
+        ...
+    }
 
-  while ($foo eq 'blah') {          #ok
-      ...
-  }
+    while ($foo eq 'blah') {          #ok
+        ...
+    }
 
 A number of people have problems figuring out the meaning of doubly
 negated expressions.  C<unless> and C<until> are both negative
@@ -182,7 +183,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks>
+L<Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks|Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks>
 
 =head1 AUTHOR
 
index f2a325c..aaa5210 100644 (file)
@@ -105,7 +105,8 @@ Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls - Write C<if($c
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -117,27 +118,27 @@ lead to double-negatives that are hard to comprehend.  The only
 tolerable usage of a postfix C<if> is when it follows a loop break
 such as C<last>, C<next>, C<redo>, or C<continue>.
 
-  do_something() if $condition;         #not ok
-  if($condition){ do_something() }      #ok
+    do_something() if $condition;         #not ok
+    if($condition){ do_something() }      #ok
 
-  do_something() while $condition;      #not ok
-  while($condition){ do_something() }   #ok
+    do_something() while $condition;      #not ok
+    while($condition){ do_something() }   #ok
 
-  do_something() unless $condition;     #not ok
-  do_something() unless ! $condition;   #really bad
-  if(! $condition){ do_something() }    #ok
+    do_something() unless $condition;     #not ok
+    do_something() unless ! $condition;   #really bad
+    if(! $condition){ do_something() }    #ok
 
-  do_something() until $condition;      #not ok
-  do_something() until ! $condition;    #really bad
-  while(! $condition){ do_something() } #ok
+    do_something() until $condition;      #not ok
+    do_something() until ! $condition;    #really bad
+    while(! $condition){ do_something() } #ok
 
-  do_something($_) for @list;           #not ok
+    do_something($_) for @list;           #not ok
 
- LOOP:
-  for my $n (0..100){
-      next if $condition;               #ok
-      last LOOP if $other_condition;    #also ok
-  }
   LOOP:
+    for my $n (0..100){
+        next if $condition;               #ok
+        last LOOP if $other_condition;    #also ok
+    }
 
 =head1 CONFIGURATION
 
@@ -146,8 +147,8 @@ giving a value for 'allow' of a string of space-delimited keywords:
 C<if>, C<for>, C<unless>, C<until>, and/or C<while>.  An example of
 specifying allowed flow-control structures in a F<.perlcriticrc> file:
 
- [ControlStructures::ProhibitPostfixControls]
- allow = for if until
   [ControlStructures::ProhibitPostfixControls]
   allow = for if until
 
 By default, all postfix control keywords are prohibited.
 
@@ -155,8 +156,8 @@ The set of flow-control functions that are exempt from the restriction
 can also be configured with the 'flowcontrol' directive in your
 F<.perlcriticrc> file:
 
- [ControlStructures::ProhibitPostfixControls]
- flowcontrol = warn die carp croak cluck confess goto exit
   [ControlStructures::ProhibitPostfixControls]
   flowcontrol = warn die carp croak cluck confess goto exit
 
 =head1 NOTES
 
index d9f2171..6e59253 100644 (file)
@@ -54,17 +54,19 @@ Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks - Write C<if(! $co
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-Conway discourages using C<unless> because it leads to double-negatives
-that are hard to understand.  Instead, reverse the logic and use C<if>.
+Conway discourages using C<unless> because it leads to
+double-negatives that are hard to understand.  Instead, reverse the
+logic and use C<if>.
 
-  unless($condition) { do_something() } #not ok
-  unless(! $no_flag) { do_something() } #really bad
-  if( ! $condition)  { do_something() } #ok
+    unless($condition) { do_something() } #not ok
+    unless(! $no_flag) { do_something() } #really bad
+    if( ! $condition)  { do_something() } #ok
 
 This Policy only covers the block-form of C<unless>.  For the postfix
 variety, see C<ProhibitPostfixControls>.
@@ -77,7 +79,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
+L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls|Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
 
 =head1 AUTHOR
 
index e926f1e..1fe2f3a 100644 (file)
@@ -101,15 +101,16 @@ Perl::Critic::Policy::ControlStructures::ProhibitUnreachableCode - Don't write c
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-This policy prohibits code following a statement which unconditionally alters
-the program flow.  This includes calls to C<exit>, C<die>, C<return>, C<next>,
-C<last> and C<goto>.  Due to common usage, C<croak> and C<confess> from
-L<Carp> are also included.
+This policy prohibits code following a statement which unconditionally
+alters the program flow.  This includes calls to C<exit>, C<die>,
+C<return>, C<next>, C<last> and C<goto>.  Due to common usage,
+C<croak> and C<confess> from L<Carp|Carp> are also included.
 
 Code is reachable if any of the following conditions are true:
 
@@ -196,7 +197,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
+L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls|Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
 
 =head1 AUTHOR
 
index 833846d..68b5b8d 100644 (file)
@@ -53,17 +53,19 @@ Perl::Critic::Policy::ControlStructures::ProhibitUntilBlocks - Write C<while(! $
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Conway discourages using C<until> because it leads to double-negatives
-that are hard to understand.  Instead, reverse the logic and use C<while>.
+that are hard to understand.  Instead, reverse the logic and use
+C<while>.
 
-  until($condition)     { do_something() } #not ok
-  until(! $no_flag)     { do_something() } #really bad
-  while( ! $condition)  { do_something() } #ok
+    until($condition)     { do_something() } #not ok
+    until(! $no_flag)     { do_something() } #really bad
+    while( ! $condition)  { do_something() } #ok
 
 This Policy only covers the block-form of C<until>.  For the postfix
 variety, see C<ProhibitPostfixControls>.
@@ -76,7 +78,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
+L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls|Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>
 
 =head1 AUTHOR
 
index 23f1dd9..fc066d0 100644 (file)
@@ -249,9 +249,11 @@ __END__
 
 Perl::Critic::Policy::Documentation::PodSpelling - Check your spelling.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -264,24 +266,25 @@ Is your documentation readable?  Hmm...
 
 Ideally, we'd like Perl::Critic to tell you when your documentation is
 inadequate.  That's hard to code, though.  So, inspired by
-L<Test::Spelling>, this module checks the spelling of your POD.  It
-does this by pulling the prose out of the code and passing it to an
-external spell checker.  It skips over words you flagged to ignore.
-If the spell checker returns any misspelled words, this policy emits a
-violation.
+L<Test::Spelling|Test::Spelling>, this module checks the spelling of
+your POD.  It does this by pulling the prose out of the code and
+passing it to an external spell checker.  It skips over words you
+flagged to ignore.  If the spell checker returns any misspelled words,
+this policy emits a violation.
 
 If anything else goes wrong -- you don't have Pod::Spell installed or
 we can't locate the spell checking program or (gasp!) your module has
 no POD -- then this policy passes.
 
 To add exceptions on a module-by-module basis, add "stopwords" as
-described in L<Pod::Spell>.  For example:
+described in L<Pod::Spell|Pod::Spell>.  For example:
+
+    =for stopword gibbles
 
-   =for stopword gibbles
+    =head1 Gibble::Manip -- manipulate your gibbles
 
-   =head1 Gibble::Manip -- manipulate your gibbles
+    =cut
 
-   =cut
 
 =head1 CONFIGURATION
 
@@ -289,32 +292,38 @@ This policy can be configured to tell which spell checker to use or to
 set a global list of spelling exceptions.  To do this, put entries in
 a F<.perlcriticrc> file like this:
 
-  [Documentation::PodSpelling]
-  spell_command = aspell list
-  stop_words = gibbles foobar
+    [Documentation::PodSpelling]
+    spell_command = aspell list
+    stop_words = gibbles foobar
 
 The default spell command is C<aspell list> and it is interpreted as a
 shell command.  We parse the individual arguments via
-L<Text::ParseWords> so feel free to use quotes around your arguments.
-If the executable path is an absolute file name, it is used as-is.  If
-it is a relative file name, we employ L<File::Which> to convert it to
-an absolute path via the C<PATH> environment variable.  As described
-in Pod::Spell and Test::Spelling, the spell checker must accept text
-on STDIN and print misspelled words one per line on STDOUT.
+L<Text::ParseWords|Text::ParseWords> so feel free to use quotes around
+your arguments.  If the executable path is an absolute file name, it
+is used as-is.  If it is a relative file name, we employ
+L<File::Which|File::Which> to convert it to an absolute path via the
+C<PATH> environment variable.  As described in Pod::Spell and
+Test::Spelling, the spell checker must accept text on STDIN and print
+misspelled words one per line on STDOUT.
+
 
 =head1 NOTES
 
-L<Pod::Spell> is not included with Perl::Critic, nor is a spell
-checking program.
+L<Pod::Spell|Pod::Spell> is not included with Perl::Critic, nor is a
+spell checking program.
+
 
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
+
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2007-2008 Chris Dolan.  Many rights reserved.
index 72194bf..bd74ac2 100644 (file)
@@ -40,31 +40,32 @@ sub violates {
     return if !$pods_ref;
 
     for my $pod (@{$pods_ref}) {
-       my $content = $pod->content;
+        my $content = $pod->content;
 
-       next if $content !~ m{^=head1 [ \t]+ NAME [ \t]*$ \s*}cgxms;
+        next if $content !~ m{^=head1 [ \t]+ NAME [ \t]*$ \s*}cgxms;
 
-       my ($pod_pkg) = $content =~ m{\G (\S+) }cgxms;
+        my ($pod_pkg) = $content =~ m{\G (\S+) }cgxms;
 
-       if (!$pod_pkg) {
-          return $self->violation( $DESC, q{Empty name declaration}, $elem );
-       }
+        if (!$pod_pkg) {
+            return $self->violation( $DESC, q{Empty name declaration}, $elem );
+        }
 
-       # idea: force NAME to match the file name in scripts?
-       return if is_script($doc); # mismatch is normal in program entry points
+        # idea: force NAME to match the file name in scripts?
+        return if is_script($doc); # mismatch is normal in program entry points
 
-       # idea: worry about POD escapes?
-       $pod_pkg =~ s{\A [CL]<(.*)>\z}{$1}gxms; # unwrap
-       $pod_pkg =~ s{\'}{::}gxms;              # perl4 -> perl5
+        # idea: worry about POD escapes?
+        $pod_pkg =~ s{\A [CL]<(.*)>\z}{$1}gxms; # unwrap
+        $pod_pkg =~ s{\'}{::}gxms;              # perl4 -> perl5
 
-       my $pkgs = $doc->find('PPI::Statement::Package');
-       # no package statement means no possible match
-       my $pkg = $pkgs ? $pkgs->[0]->namespace : q{};
-       $pkg =~ s{\'}{::}gxms;
+        my $pkgs = $doc->find('PPI::Statement::Package');
+        # no package statement means no possible match
+        my $pkg = $pkgs ? $pkgs->[0]->namespace : q{};
+        $pkg =~ s{\'}{::}gxms;
 
-       return if $pkg eq $pod_pkg;
-       return $self->violation( $DESC, $EXPL, $pod );
+        return if $pkg eq $pod_pkg;
+        return $self->violation( $DESC, $EXPL, $pod );
     }
+
     return;  # no NAME section found
 }
 
@@ -80,9 +81,11 @@ __END__
 
 Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName - The C<=head1 NAME> section should match the package.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic> distribution.
+
 
 =head1 DESCRIPTION
 
@@ -91,10 +94,12 @@ This Policy is part of the core L<Perl::Critic> distribution.
 
 This Policy is not configurable except for the standard options.
 
+
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2008 Chris Dolan
index 90496b4..2b581cf 100644 (file)
@@ -70,19 +70,21 @@ __END__
 
 Perl::Critic::Policy::Documentation::RequirePodAtEnd - All POD should be after C<__END__>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Perl stops processing code when it sees an C<__END__> statement.  So,
-to save processing time, it's faster to put
-documentation after the C<__END__>.  Also, writing all the POD in one
-place usually leads to a more cohesive document, rather than being
-forced to follow the layout of your code.  This policy issues
-violations if any POD is found before an C<__END__>.
+to save processing time, it's faster to put documentation after the
+C<__END__>.  Also, writing all the POD in one place usually leads to a
+more cohesive document, rather than being forced to follow the layout
+of your code.  This policy issues violations if any POD is found
+before an C<__END__>.
 
 
 =head1 CONFIGURATION
@@ -93,24 +95,25 @@ This Policy is not configurable except for the standard options.
 =head1 NOTES
 
 Some folks like to use C<=for>, and C<=begin>, and C<=end> tags to
-create block comments in-line with their code.  Since those tags aren't
-usually part of the documentation, this Policy does allows them to
-appear before the C<__END__> statement.
+create block comments in-line with their code.  Since those tags
+aren't usually part of the documentation, this Policy does allows them
+to appear before the C<__END__> statement.
 
-  =begin comments
+    =begin comments
 
-  frobulate()
-  Accepts:  A list of things to frobulate
-  Returns:  True if succesful
+    frobulate()
+    Accepts:  A list of things to frobulate
+    Returns:  True if succesful
 
-  =end comments
+    =end comments
 
-  sub frobulate { ... }
+    sub frobulate { ... }
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2006-2008 Chris Dolan.  All rights reserved.
index cd78153..d6e9204 100644 (file)
@@ -356,18 +356,21 @@ __END__
 
 Perl::Critic::Policy::Documentation::RequirePodSections - Organize your POD into the customary sections.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 This Policy requires your POD to contain certain C<=head1> sections.
 If the file doesn't contain any POD at all, then this Policy does not
-apply.  Tools like L<Module::Starter> make it really easy to ensure
-that every module has the same documentation framework, and they can
-save you lots of keystrokes.
+apply.  Tools like L<Module::Starter|Module::Starter> make it really
+easy to ensure that every module has the same documentation framework,
+and they can save you lots of keystrokes.
+
 
 =head1 DEFAULTS
 
@@ -375,34 +378,36 @@ Different POD sections are required, depending on whether the file is
 a library or program (which is determined by the presence or absence
 of a perl shebang line).
 
-             Default Required POD Sections
-
-   Perl Libraries                     Perl Programs
-   ------------------------------------------------------
-   NAME                               NAME
-   VERSION
-   SYNOPSIS                           USAGE
-   DESCRIPTION                        DESCRIPTION
-   SUBROUTINES/METHODS                REQUIRED ARGUMENTS
-                                      OPTIONS
-   DIAGNOSTICS                        DIAGNOSTICS
-                                      EXIT STATUS
-   CONFIGURATION AND ENVIRONMENT      CONFIGURATION
-   DEPENDENCIES                       DEPENDENCIES
-   INCOMPATIBILITIES                  INCOMPATIBILITIES
-   BUGS AND LIMITATIONS               BUGS AND LIMITATIONS
-   AUTHOR                             AUTHOR
-   LICENSE AND COPYRIGHT              LICENSE AND COPYRIGHT
+                Default Required POD Sections
+
+    Perl Libraries                     Perl Programs
+    ------------------------------------------------------
+    NAME                               NAME
+    VERSION
+    SYNOPSIS                           USAGE
+    DESCRIPTION                        DESCRIPTION
+    SUBROUTINES/METHODS                REQUIRED ARGUMENTS
+                                        OPTIONS
+    DIAGNOSTICS                        DIAGNOSTICS
+                                        EXIT STATUS
+    CONFIGURATION AND ENVIRONMENT      CONFIGURATION
+    DEPENDENCIES                       DEPENDENCIES
+    INCOMPATIBILITIES                  INCOMPATIBILITIES
+    BUGS AND LIMITATIONS               BUGS AND LIMITATIONS
+    AUTHOR                             AUTHOR
+    LICENSE AND COPYRIGHT              LICENSE AND COPYRIGHT
+
 
 =head1 CONFIGURATION
 
 The default sections above are derived from Damian Conway's I<Perl
 Best Practices> book.  Since the book has been published, Conway has
-released L<Module::Starter::PBP>, which has different names for some
-of the sections, and adds some more.  Also, the book and module use
-Australian spelling, while the authors of this module have previously
-used American spelling.  To sort this all out, there are a couple of
-options that can be used: C<source> and C<language>.
+released L<Module::Starter::PBP|Module::Starter::PBP>, which has
+different names for some of the sections, and adds some more.  Also,
+the book and module use Australian spelling, while the authors of this
+module have previously used American spelling.  To sort this all out,
+there are a couple of options that can be used: C<source> and
+C<language>.
 
 The C<source> option has two generic values, C<book> and
 C<module_starter_pbp>, and two version-specific values,
@@ -421,15 +426,15 @@ the addition of C<EXIT STATUS>.  To get precisely the sections as
 specified in the book, put the following in your F<.perlcriticrc>
 file:
 
-  [Documentation::RequirePodSections]
-  source   = book_first_edition
-  language = en_AU
+    [Documentation::RequirePodSections]
+    source   = book_first_edition
+    language = en_AU
 
 If you want to use
 
-  [Documentation::RequirePodSections]
-  source   = module_starter_pbp
-  language = en_US
+    [Documentation::RequirePodSections]
+    source   = module_starter_pbp
+    language = en_US
 
 you will need to modify your F<~/.module-starter/PBP/Module.pm>
 template because it is generated using Australian spelling.
@@ -443,9 +448,10 @@ giving values for C<script_sections> and C<lib_sections> of a string
 of pipe-delimited required POD section names.  An example of entries
 in a F<.perlcriticrc> file:
 
-  [Documentation::RequirePodSections]
-  lib_sections    = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR
-  script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR
+    [Documentation::RequirePodSections]
+    lib_sections    = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR
+    script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR
+
 
 =head1 LIMITATIONS
 
@@ -453,10 +459,12 @@ Currently, this Policy does not look for the required POD sections
 below the C<=head1> level.  Also, it does not require the sections to
 appear in any particular order.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2006-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index 0248be6..8bd9c6d 100644 (file)
@@ -354,11 +354,12 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Policy::ErrorHandling::RequireCarping - Use functions from L<Carp> instead of C<warn> or C<die>.
+Perl::Critic::Policy::ErrorHandling::RequireCarping - Use functions from L<Carp|Carp> instead of C<warn> or C<die>.
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -367,14 +368,14 @@ The C<die> and C<warn> functions both report the file and line number
 where the exception occurred.  But if someone else is using your
 subroutine, they usually don't care where B<your> code blew up.
 Instead, they want to know where B<their> code invoked the subroutine.
-The L<Carp> module provides alternative methods that report the
+The L<Carp|Carp> module provides alternative methods that report the
 exception from the caller's file and line number.
 
 By default, this policy will not complain about C<die> or C<warn>, if
 it can determine that the message will always result in a terminal
 newline.  Since perl suppresses file names and line numbers in this
 situation, it is assumed that no stack traces are desired either and
-none of the L<Carp> functions are necessary.
+none of the L<Carp|Carp> functions are necessary.
 
     die "oops" if $explosion;             #not ok
     warn "Where? Where?!" if $tiger;      #not ok
@@ -404,7 +405,7 @@ will disallow all uses of C<die> and C<warn>.
 
 =head1 SEE ALSO
 
-L<Carp::Always>
+L<Carp::Always|Carp::Always>
 
 =head1 AUTHOR
 
index ef5c11c..a908518 100644 (file)
@@ -258,7 +258,8 @@ Perl::Critic::Policy::ErrorHandling::RequireCheckingReturnValueOfEval - You can'
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
index 790db24..d3e428d 100644 (file)
@@ -71,7 +71,8 @@ Perl::Critic::Policy::InputOutput::ProhibitBacktickOperators - Discourage stuff
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -116,8 +117,8 @@ assign the result to a variable.
 This policy also prohibits the generalized form of backticks seen as
 C<qx{}>.
 
-See L<perlipc> for more discussion on using C<wait()> instead of
-C<$SIG{CHLD} = 'IGNORE'>.
+See L<perlipc|perlipc> for more discussion on using C<wait()> instead
+of C<$SIG{CHLD} = 'IGNORE'>.
 
 =head1 AUTHOR
 
index 77a935b..d797b01 100644 (file)
@@ -64,7 +64,8 @@ Perl::Critic::Policy::InputOutput::ProhibitBarewordFileHandles - Write C<open my
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -74,8 +75,9 @@ because they are global, and you have no idea if that symbol already
 points to some other file handle.  You can mitigate some of that risk
 by C<local>izing the symbol first, but that's pretty ugly.  Since Perl
 5.6, you can use an undefined scalar variable as a lexical reference
-to an anonymous filehandle.  Alternatively, see the L<IO::Handle> or
-L<IO::File> or L<FileHandle> modules for an object-oriented approach.
+to an anonymous filehandle.  Alternatively, see the
+L<IO::Handle|IO::Handle> or L<IO::File|IO::File> or
+L<FileHandle|FileHandle> modules for an object-oriented approach.
 
     open FH, '<', $some_file;           #not ok
     open my $fh, '<', $some_file;       #ok
@@ -92,9 +94,9 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<IO::Handle>
+L<IO::Handle|IO::Handle>
 
-L<IO::File>
+L<IO::File|IO::File>
 
 =head1 AUTHOR
 
index fbf6e83..960c9ba 100644 (file)
@@ -54,7 +54,8 @@ Perl::Critic::Policy::InputOutput::ProhibitExplicitStdin - Use "<>" or "<ARGV>"
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -75,7 +76,7 @@ one of the following two equivalent forms:
   }
 
 If you want to prompt for user input, try special purpose modules like
-L<IO::Prompt>.
+L<IO::Prompt|IO::Prompt>.
 
 
 =head1 CONFIGURATION
@@ -87,7 +88,8 @@ This Policy is not configurable except for the standard options.
 
 Due to a bug in the current version of PPI (v1.119_03) and earlier,
 the readline operator is often misinterpreted as less-than and
-greater-than operators after a comma.  Therefore, this policy misses important cases like
+greater-than operators after a comma.  Therefore, this policy misses
+important cases like
 
   my $content = join '', <STDIN>;
 
@@ -100,7 +102,8 @@ violations automatically.
 
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
 
 =head1 AUTHOR
 
index 57f4e3c..9567e22 100644 (file)
@@ -51,14 +51,15 @@ Perl::Critic::Policy::InputOutput::ProhibitInteractiveTest - Use prompt() instea
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 The C<-t> operator is fragile and complicated.  When you are testing
 whether C<STDIN> is interactive, It's much more robust to use
-well-tested CPAN modules like L<IO::Interactive>.
+well-tested CPAN modules like L<IO::Interactive|IO::Interactive>.
 
 
 =head1 CONFIGURATION
index 53bb199..0eb0a88 100644 (file)
@@ -58,11 +58,12 @@ __END__
 
 =head1 NAME
 
-Perl::Critic::Policy::InputOutput::ProhibitJoinedReadline - Use C<local $/ = undef> or L<File::Slurp> instead of joined readline.
+Perl::Critic::Policy::InputOutput::ProhibitJoinedReadline - Use C<local $/ = undef> or L<File::Slurp|File::Slurp> instead of joined readline.
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -71,11 +72,12 @@ It's really easy to slurp a whole filehandle in at once with C<join
 q{}, <$fh>>, but that's inefficient -- Perl goes to the trouble of
 splitting the file into lines only to have that work thrown away.
 
-To save performance, either slurp the filehandle without splitting like so:
+To save performance, either slurp the filehandle without splitting
+like so:
 
   do { local $/ = undef; <$fh> }
 
-or use L<File::Slurp>, which is even faster.
+or use L<File::Slurp|File::Slurp>, which is even faster.
 
 
 =head1 CONFIGURATION
@@ -88,17 +90,21 @@ This Policy is not configurable except for the standard options.
 Due to a bug in the current version of PPI (v1.119_03) and earlier,
 the readline operator is often misinterpreted as less-than and
 greater-than operators after a comma.  Therefore, this policy only
-works well on the empty filehandle, C<<>>.  When PPI is fixed, this
-should just start working.
+works well on the empty filehandle, C<< <> >>.  When PPI is fixed,
+this should just start working.
+
 
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
+
 
 =head1 AUTHOR
 
 Chris Dolan <cdolan@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2007-2008 Chris Dolan.  Many rights reserved.
index a99041d..30a900e 100644 (file)
@@ -57,7 +57,8 @@ Perl::Critic::Policy::InputOutput::ProhibitOneArgSelect - Never write C<select($
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -83,7 +84,7 @@ This Policy is not configurable except for the standard options.
 
 =head1 SEE ALSO
 
-L<IO::Handle>.
+L<IO::Handle|IO::Handle>.
 
 =head1 AUTHOR
 
index d203121..9d383f0 100644 (file)
@@ -55,16 +55,17 @@ Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop - Write C<< while(
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 Using the readline operator in a C<for> or C<foreach> loop is very
-slow.  The iteration list of the loop creates a list context,
-which causes the readline operator to read the entire input stream
-before iteration even starts.  Instead, just use a C<while> loop,
-which only reads one line at a time.
+slow.  The iteration list of the loop creates a list context, which
+causes the readline operator to read the entire input stream before
+iteration even starts.  Instead, just use a C<while> loop, which only
+reads one line at a time.
 
   for my $line ( <$file_handle> ){ do_something($line) }      #not ok
   while ( my $line = <$file_handle> ){ do_something($line) }  #ok
index aed7922..e32c1d1 100644 (file)
@@ -72,14 +72,15 @@ Perl::Critic::Policy::InputOutput::ProhibitTwoArgOpen - Write C<< open $fh, q{<}
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 The three-argument form of C<open> (introduced in Perl 5.6) prevents
 subtle bugs that occur when the filename starts with funny characters
-like '>' or '<'.  The L<IO::File> module provides a nice
+like '>' or '<'.  The L<IO::File|IO::File> module provides a nice
 object-oriented interface to filehandles, which I think is more
 elegant anyway.
 
@@ -89,8 +90,8 @@ elegant anyway.
   use IO::File;
   my $fh = IO::File->new( 'output.txt', q{>} ); # even better!
 
-It's also more explicitly clear to define the input mode of the
-file, as in the difference between these two:
+It's also more explicitly clear to define the input mode of the file,
+as in the difference between these two:
 
   open( $fh, 'foo.txt' );       # BAD: Reader must think what default mode is
   open( $fh, '<', 'foo.txt' );  # GOOD: Reader can see open mode
@@ -113,9 +114,9 @@ that loophole.
 
 =head1 SEE ALSO
 
-L<IO::Handle>
+L<IO::Handle|IO::Handle>
 
-L<IO::File>
+L<IO::File|IO::File>
 
 =head1 AUTHOR
 
index 885d8cf..3131205 100644 (file)
@@ -94,7 +94,8 @@ Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint - Write C<pr
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
index cb6f9ff..87e9bd3 100644 (file)
@@ -199,27 +199,29 @@ Perl::Critic::Policy::InputOutput::RequireBriefOpen - Close filehandles as soon
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
 One way that production systems fail unexpectedly is by running out of
-filehandles.  Filehandles are a finite resource on every operating system that
-I'm aware of, and running out of them is virtually impossible to recover from.
-The solution is to not run out in the first place.  What causes programs to
-run out of filehandles?  Usually, it's leaks: you open a filehandle and forget
-to close it, or just wait a really long time before closing it.
-
-This problem is rarely exposed by test systems, because the tests rarely run
-long enough or have enough load to hit the filehandle limit.  So, the best way
-to avoid the problem is 1) always close all filehandles that you open and 2)
-close them as soon as is practical.
-
-This policy takes note of calls to C<open()> where there is no matching
-C<close()> call within C<N> lines of code.  If you really need to do a lot of
-processing on an open filehandle, then you can move that processing to another
-method like this:
+filehandles.  Filehandles are a finite resource on every operating
+system that I'm aware of, and running out of them is virtually
+impossible to recover from.  The solution is to not run out in the
+first place.  What causes programs to run out of filehandles?
+Usually, it's leaks: you open a filehandle and forget to close it, or
+just wait a really long time before closing it.
+
+This problem is rarely exposed by test systems, because the tests
+rarely run long enough or have enough load to hit the filehandle
+limit.  So, the best way to avoid the problem is 1) always close all
+filehandles that you open and 2) close them as soon as is practical.
+
+This policy takes note of calls to C<open()> where there is no
+matching C<close()> call within C<N> lines of code.  If you really
+need to do a lot of processing on an open filehandle, then you can
+move that processing to another method like this:
 
     sub process_data_file {
         my ($self, $filename) = @_;
@@ -237,20 +239,22 @@ method like this:
         return;
     }
 
-As a special case, this policy also allows code to return the filehandle after
-the C<open> instead of closing it.  Just like the close, however, that
-C<return> has to be within the right number of lines.  From there, you're on
-your own to figure out whether the code is promptly closing the filehandle.
+As a special case, this policy also allows code to return the
+filehandle after the C<open> instead of closing it.  Just like the
+close, however, that C<return> has to be within the right number of
+lines.  From there, you're on your own to figure out whether the code
+is promptly closing the filehandle.
 
 The STDIN, STDOUT, and STDERR handles are exempt from this policy.
 
 
 =head1 CONFIGURATION
 
-This policy allows C<close()> invocations to be up to C<N> lines after their
-corresponding C<open()> calls, where C<N> defaults to 9.  You can override
-this to set it to a different number with the C<lines> setting.  To do this,
-put entries in a F<.perlcriticrc> file like this:
+This policy allows C<close()> invocations to be up to C<N> lines after
+their corresponding C<open()> calls, where C<N> defaults to 9.  You
+can override this to set it to a different number with the C<lines>
+setting.  To do this, put entries in a F<.perlcriticrc> file like
+this:
 
   [InputOutput::RequireBriefOpen]
   lines = 5
@@ -260,14 +264,15 @@ put entries in a F<.perlcriticrc> file like this:
 
 =head2 C<IO::File-E<gt>new>
 
-This policy only looks for explicit C<open> calls.  It does not detect calls
-to C<CORE::open> or C<IO::File-E<gt>new> or the like.
+This policy only looks for explicit C<open> calls.  It does not detect
+calls to C<CORE::open> or C<IO::File-E<gt>new> or the like.
 
 
 =head2 Is it the right lexical?
 
-We don't currently check for redeclared filehandles.  So the following code
-is false negative, for example, because the outer scoped filehandle is not closed:
+We don't currently check for redeclared filehandles.  So the following
+code is false negative, for example, because the outer scoped
+filehandle is not closed:
 
     open my $fh, '<', $file1 or croak;
     if (open my $fh, '<', $file2) {
@@ -275,14 +280,15 @@ is false negative, for example, because the outer scoped filehandle is not close
         close $fh;
     }
 
-This is a contrived example, but it isn't uncommon for people to use C<$fh>
-for the name of the filehandle every time.  Perhaps it's time to think of
-better variable names...
+This is a contrived example, but it isn't uncommon for people to use
+C<$fh> for the name of the filehandle every time.  Perhaps it's time
+to think of better variable names...
 
 
 =head1 CREDITS
 
-Initial development of this policy was supported by a grant from the Perl Foundation.
+Initial development of this policy was supported by a grant from the
+Perl Foundation.
 
 
 =head1 AUTHOR
index f5e5ff0..41ae9a9 100644 (file)
@@ -56,13 +56,15 @@ Perl::Critic::Policy::InputOutput::RequireCheckedClose - Write C<< my $error = c
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-The perl builtin I/O function C<close> returns a false value on failure. That
-value should be checked to ensure that the close was successful.
+The perl builtin I/O function C<close> returns a false value on
+failure. That value should be checked to ensure that the close was
+successful.
 
 
   my $error = close $filehandle;                   # ok
@@ -81,8 +83,8 @@ Andrew Moore <amoore@mooresystems.com>
 
 =head1 ACKNOWLEDGMENTS
 
-This policy module is based heavily on policies written by Jeffrey Ryan
-Thalhammer <thaljef@cpan.org>.
+This policy module is based heavily on policies written by Jeffrey
+Ryan Thalhammer <thaljef@cpan.org>.
 
 =head1 COPYRIGHT
 
index a32680b..097f495 100644 (file)
@@ -56,13 +56,15 @@ Perl::Critic::Policy::InputOutput::RequireCheckedOpen - Write C<< my $error = op
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-The perl builtin I/O function C<open> returns a false value on failure. That
-value should always be checked to ensure that the open was successful.
+The perl builtin I/O function C<open> returns a false value on
+failure. That value should always be checked to ensure that the open
+was successful.
 
 
   my $error = open( $filehandle, $mode, $filename );                  # ok
@@ -81,8 +83,8 @@ Andrew Moore <amoore@mooresystems.com>
 
 =head1 ACKNOWLEDGMENTS
 
-This policy module is based heavily on policies written by Jeffrey Ryan
-Thalhammer <thaljef@cpan.org>.
+This policy module is based heavily on policies written by Jeffrey
+Ryan Thalhammer <thaljef@cpan.org>.
 
 =head1 COPYRIGHT
 
index 3754a90..72a9cfc 100644 (file)
@@ -109,7 +109,8 @@ Perl::Critic::Policy::InputOutput::RequireCheckedSyscalls - Return value of flag
 
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -118,7 +119,7 @@ This performs identically to InputOutput::RequireCheckedOpen/Close
 except that this is configurable to apply to any function, whether
 core or user-defined.
 
-If your module uses L<Fatal> or C<Fatal::Exception>, then any
+If your module uses L<Fatal|Fatal> or C<Fatal::Exception>, then any
 functions wrapped by those modules will not trigger this policy.  For
 example:
 
index 2290f33..1e3ff0c 100644 (file)
@@ -51,19 +51,23 @@ __END__
 
 Perl::Critic::Policy::Miscellanea::ProhibitFormats - Do not use C<format>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
 
-Formats are one of the oldest features of Perl.  Unfortunately, they suffer
-from several limitations.  Formats are static and cannot be easily defined
-at run time.  Also, formats depend on several obscure global variables.
+Formats are one of the oldest features of Perl.  Unfortunately, they
+suffer from several limitations.  Formats are static and cannot be
+easily defined at run time.  Also, formats depend on several obscure
+global variables.
 
-For more modern reporting tools, consider using one of the template frameworks
-like L<Template> or try the L<Perl6::Form> module.
+For more modern reporting tools, consider using one of the template
+frameworks like L<Template|Template> or try the
+L<Perl6::Form|Perl6::Form> module.
 
 
 =head1 CONFIGURATION
index 57b54d4..b675ccd 100644 (file)
@@ -51,9 +51,11 @@ __END__
 
 Perl::Critic::Policy::Miscellanea::ProhibitTies - Do not use C<tie>.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -74,6 +76,7 @@ This Policy is not configurable except for the standard options.
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
index e7c5aae..1e82e79 100644 (file)
@@ -136,9 +136,11 @@ __END__
 
 Perl::Critic::Policy::Miscellanea::RequireRcsKeywords - Put source-control keywords in every file.
 
+
 =head1 AFFILIATION
 
-This Policy is part of the core L<Perl::Critic> distribution.
+This Policy is part of the core L<Perl::Critic|Perl::Critic>
+distribution.
 
 
 =head1 DESCRIPTION
@@ -149,32 +151,36 @@ file helps the reader know where the file comes from, in case he or
 she needs to modify it.  This Policy scans your file for comments that
 look like this:
 
-  # $Revision$
-  # $Source: /myproject/lib/foo.pm $
+    # $Revision$
+    # $Source: /myproject/lib/foo.pm $
 
 A common practice is to use the C<Revision> keyword to automatically
 define the C<$VERSION> variable like this:
 
-  our ($VERSION) = '$Revision$' =~ m{ \$Revision: \s+ (\S+) }x;
+    our ($VERSION) = '$Revision$' =~ m{ \$Revision: \s+ (\S+) }x;
+
 
 =head1 CONFIGURATION
 
-By default, this policy only requires the C<Revision>, C<Source>, and C<Date>
-keywords.  To specify alternate keywords, specify a value for C<keywords> of a
-whitespace delimited series of keywords (without the dollar-signs).  This would
-look something like the following in a F<.perlcriticrc> file:
+By default, this policy only requires the C<Revision>, C<Source>, and
+C<Date> keywords.  To specify alternate keywords, specify a value for
+C<keywords> of a whitespace delimited series of keywords (without the
+dollar-signs).  This would look something like the following in a
+F<.perlcriticrc> file:
 
-  [Miscellanea::RequireRcsKeywords]
-  keywords = Revision Source Date Author Id
+    [Miscellanea::RequireRcsKeywords]
+    keywords = Revision Source Date Author Id
 
 See the documentation on RCS for a list of supported keywords.  Many
 source control systems are descended from RCS, so the keywords
 supported by CVS and Subversion are probably the same.
 
+
 =head1 AUTHOR
 
 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
+
 =head1 COPYRIGHT
 
 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.