Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::PolicyPeUserCContributedcPerloDocumentationProhibitLinkToSelf(3)

NAME
       Perl::Critic::Policy::Documentation::ProhibitLinkToSelf - don't L<>
       link to own POD

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It asks	you
       not to use "L<>"	markup to refer	to a POD document itself.

	   =head1 NAME

	   My::Package - something

	   =head1 DESCRIPTION

	   L<My::Package> does blah blah ...	 # bad

	   =head1 SEE ALSO

	   L<My::Package>			 # bad

       The idea	is that	it doesn't make	sense to link to a document from
       within itself.  If rendered as a	clickable link then it may suggest
       there's somewhere else to go to read about the module when in fact
       you're already looking at it.

       This is only a minor thing though, so this policy is low	severity and
       under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic).

       In ordinary text	the suggestion is plain	"C<>" or similar for one's 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 there's no need to "see
       also" what you've just read.

       If linking to a particular section within one's 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 doesn't 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 that's a	good idea.

	   =head1 NAME

	   My::Package -- blah

	   My::Package::Parser -- and its parser

	   =head1 DESCRIPTION

       It's always possible an "L<>" is	right and in fact the "NAME" appearing
       is wrong.  A violation on the "L<>" will	at least show there's
       something fishy in the one or the other.

   Disabling
       If you don't care about this then you can always	disable
       "ProhibitLinkToSelf" from your .perlcriticrc file in the	usual way (see
       "CONFIGURATION" in Perl::Critic),

	   [-Documentation::ProhibitLinkToSelf]

       If you like to almost always put	"L<>" on module	names, including in
       the module's 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".

SEE ALSO
       Perl::Critic::Pulp, Perl::Critic

       Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName,
       Perl::Critic::Policy::Documentation::ProhibitAdjacentLinks

HOME PAGE
       <http://user42.tuxfamily.org/perl-critic-pulp/index.html>

COPYRIGHT
       Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017 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 version.

       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 more details.

       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/>.

perl v5.24.1	    Perl::Critic::Policy::Documentation::ProhibitLinkToSelf(3)

NAME | DESCRIPTION | SEE ALSO | HOME PAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::Documentation::ProhibitLinkToSelf&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help