Perl::...adings(3pm)

📦
version 100 · 7 versions
, in ubuntu resolute, ubuntu stonking

💖 Perl::Critic::Policy::Documentation::ProhibitDuplicateHeadings 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section of the manual (it's the Perl::...adings(3pm) one, yes the name is doing the most, we love her anyway 🫶), and we're talking about the policy Perl::Critic::Policy::Documentation::ProhibitDuplicateHeadings.

✨ NAME ✨

Perl::Critic::Policy::Documentation::ProhibitDuplicateHeadings — bestie, literally just: don't duplicate =head names. That's it. That's the whole vibe check. 💅

🌸 DESCRIPTION 🌸

So this policy is part of the "Perl::Critic::Pulp" add-on (yes she has a whole little friend group, we'll get to that). What she wants from you is simple: don't use the same heading name twice in your =head POD commands.

=head1 SOMETHING

=head1 SOMETHING      # bad, duplicate

Like… why would you do that. 🙈

Duplication is usually a mistake — maybe it's too much cut-and-paste, maybe it's leftover template junk, or maybe it's two chunks of text that were supposed to be together this whole time and just got separated. Tragic. On that basis this policy is medium severity and lives under the "bugs" theme (peep "POLICY THEMES" in Perl::Critic for more on that).

🎀 Default Uniqueness 🎀

By default the policy demands that a given heading is unique to its ancestors, its siblings, and the immediately adjacent heading, irrespective of level. This is designed to be how us human readers actually perceive the scope of headings and subheadings — plus adjacency, just in case a mixture of heading levels would let a duplicate otherwise go undetected. Sneaky little duplicates.

For example, an ancestor dupe:

=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

But!! A subheading can be repeated if it's under a different higher heading. For example the following two "Details" are cousins, so they're allowed. Family reunion rules, okay:

=head1 One

=head2 Details

=head1 Two

=head2 Details          # ok

👑 All Unique 👑

Option "uniqueness=all" (see "CONFIGURATION" below 👇) turns it up a notch to a stricter rule, so that all "=head" names must be unique throughout the document, irrespective of levels and structure. No exceptions, periodt.

=head3 Foo

=head1 Bar

=head3 Foo             # bad

One use for this is to make sure all headings can be reached by an "L<>" link. Because an "L<>" only has the heading name — no level, no path — 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. They said "first come, first served" and meant it. 💀)

Ngl this rule is often too strict. It can be genuinely good to have similar subheadings like "Details" as shown above, with no need to make such sub-parts reachable by a link. Sometimes a girl just wants two Details sections and that's fine.

🦋 Disabling 🦋

If you don't care about any of this at all (valid, live your truth), 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. (So don't get too attached, bestie. She's allowed to grow. 🌱)

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 2013, 2014, 2015, 2016, 2017, 2019, 2021 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/>.

okay and that's the whole page bestie, mwah 💋 — this was perl v5.40.1, dated 2025-10-21, and it came to you from the Perl::...adings(3pm) corner of the world. go forth and make your headings unique (or at least ancestor-sibling-adjacent unique, we're not monsters). 🧚✨

📦 where this page comes from