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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic:Perl::CriUser:ContributeduPerlaDocumentationtDuplicateHeadings(3)

NAME
       Perl::Critic::Policy::Documentation::ProhibitDuplicateHeadings -	don't
       duplicate =head names

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It asks	you
       not to duplicate	heading	names in "=head" POD commands.

	   =head1 SOMETHING

	   =head1 SOMETHING	 # bad,	duplicate

       Duplication is usually a	mistake, perhaps too much cut-and-paste, or a
       leftover	from a template, or perhaps text in two	places which ought to
       be together.  On	that basis this	policy is medium severity and under
       the "bugs" theme	(see "POLICY THEMES" in	Perl::Critic).

   Default Uniqueness
       The policy default is to	demand that a given heading is unique to its
       ancestors, siblings, and	to the immediately adjacent heading
       irrespective of level.  This is designed	to be how human	readers
       perceive	the scope of headings and subheadings, plus adjacency in case
       a mixture of heading levels would let a duplicate otherwise go
       undetected.  For	example

	   =head1 Top

	   =head2 Subhead

	   =head3 Top		   # bad, duplicates its ancestor head1

       Or siblings

	   =head1 Top

	   =head2 Down

	   =head2 Another

	   =head2 Down		   # bad, duplicates sibling head2

       Or adjacent

	   =head2 Blah

	   =head1 Blah		   # bad, duplicates adjacent

       A subheading can	be repeated if it's under a different higher heading.
       For example the following two "Details" are cousins, so allowed.

	   =head1 One

	   =head2 Details

	   =head1 Two

	   =head2 Details	   # ok

   All Unique
       Option "uniqueness=all" (see "CONFIGURATION" below) applies a stricter
       rule so that all	"=head"	names must be unique throughout	the document,
       irrespective of levels and structure.

	   =head3 Foo

	   =head1 Bar

	   =head3 Foo		  # bad

       One use for this	is to ensure all headings can be reached by an "L<>"
       link.  An "L<>" only has	the heading name, no level or path, so if
       there's any duplication among the names then only the first of each
       duplicate will be reachable.  (The POD browsers usually go to the first
       among duplicates.)

       This rule is often too strict.  It can be good to have similar
       subheadings like	"Details" as shown above, with no need to make such
       sub-parts reachable by a	link.

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

	   [-Documentation::ProhibitDuplicateHeadings]

CONFIGURATION
       "uniqueness" (string, default "default")
	   The uniqueness to be	enforced on each heading.  The value is	a
	   comma-separated list	of

	       default	   currently "ancestor,sibling,adjacent"
	       ancestor	   don't duplicate parent, grandparent,	etc
	       sibling	   same	level and parent
	       adjacent	   immediately preceding, irrespective of level
	       all	   all headings

	   The default is "default" and	the intention is to have default mean
	   a sensible set of restrictions, though precisely what it might be
	   could change.

	   For example in your .perlcriticrc file

	       [Documentation::ProhibitDuplicateHeadings]
	       uniqueness=ancestor,adjacent

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

       Perl::Critic::Policy::Documentation::ProhibitDuplicateSeeAlso,
       Perl::Critic::Policy::Documentation::RequirePodSections

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

COPYRIGHT
       Copyright 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::ProhibitDuplicateHeadings(3)

NAME | DESCRIPTION | CONFIGURATION | 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::ProhibitDuplicateHeadings&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help