This policy is part of the Perl::Critic::Pulp
add-on. It asks you not to use L<> markup to refer to a POD
My::Package - something
L<My::Package> does blah blah ... # bad
=head1 SEE ALSO
L<My::Package> # bad
The idea is that it doesnt make sense to link to a document from within
itself. If rendered as a clickable link then it may suggest theres
somewhere else to go to read about the module when in fact youre already
looking at it.
This is only a minor thing though, so this policy is under the cosmetic
theme (see POLICY THEMES in Perl::Critic) and low priority.
In ordinary text the suggestion is plain C<> or similar for
ones own module name,
C<My::Package> does something something ... # ok
In a SEE ALSO a link to self in very likely a typo, or too much cut and
paste, or at least pretty unnecessary since theres no need to see also
what youve just read.
If linking to a particular section within ones own document then use
L<> with just the section part. This will probably give
better looking output from the formatters too,
L<My::Package/SECTION> # bad
L</SECTION> # ok
For this policy the name of the POD is picked out of the =head1 NAME
section, so doesnt depend on the filename or directory where perlcritic
is run. In the current code multiple names can be given in man-page style.
Not sure if thats a good idea.
My::Package -- blah
My::Package::Parser -- and its parser
Of course its always possible an L<> is right and its the
NAME part which is wrong. A violation on the L<> will at
least show theres something fishy in the one or the other.
If you dont care about this then you can always disable
ProhibitLinkToSelf from your .perlcriticrc file in the usual way (see
CONFIGURATION in Perl::Critic),
If you like to almose always put L<> on module names,
including in the modules own POD, then disable this policy. Maybe an
option in the future could allow links to self in ordinary text but prohibit
in SEE ALSO.
Copyright 2011, 2012, 2013, 2014, 2015 Kevin Ryde
Perl-Critic-Pulp is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
Perl-Critic-Pulp is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
You should have received a copy of the GNU General Public License along with
Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.