.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::Documentation::RequirePodSections 3pm"
.TH Perl::Critic::Policy::Documentation::RequirePodSections 3pm "2018-07-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Perl::Critic::Policy::Documentation::RequirePodSections \- Organize your POD into the customary sections.
.SH "AFFILIATION"
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Policy requires your \s-1POD\s0 to contain certain \f(CW\*(C`=head1\*(C'\fR sections.
If the file doesn't contain any \s-1POD\s0 at all, then this Policy does not
apply.  Tools like Module::Starter make it really
easy to ensure that every module has the same documentation framework,
and they can save you lots of keystrokes.
.SH "DEFAULTS"
.IX Header "DEFAULTS"
Different \s-1POD\s0 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).
.PP
.Vb 1
\&                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
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The default sections above are derived from Damian Conway's \fIPerl
Best Practices\fR book.  Since the book has been published, Conway has
released 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: \f(CW\*(C`source\*(C'\fR and
\&\f(CW\*(C`language\*(C'\fR.
.PP
The \f(CW\*(C`source\*(C'\fR option has two generic values, \f(CW\*(C`book\*(C'\fR and
\&\f(CW\*(C`module_starter_pbp\*(C'\fR, and two version-specific values,
\&\f(CW\*(C`book_first_edition\*(C'\fR and \f(CW\*(C`module_starter_pbp_0_0_3\*(C'\fR.  Currently, the
generic values map to the corresponding version-specific values, but
may change as new versions of the book and module are released, so use
these if you want to keep up with the latest and greatest.  If you
want things to remain stable, use the version-specific values.
.PP
The \f(CW\*(C`language\*(C'\fR option has a default, unnamed value but also accepts
values of \f(CW\*(C`en_AU\*(C'\fR and \f(CW\*(C`en_US\*(C'\fR.  The reason the unnamed value exists
is because the default values for programs don't actually match the
book, even taking spelling into account, i.e. \f(CW\*(C`CONFIGURATION\*(C'\fR instead
of \f(CW\*(C`CONFIGURATION AND ENVIRONMENT\*(C'\fR, the removal of \f(CW\*(C`VERSION\*(C'\fR, and
the addition of \f(CW\*(C`EXIT STATUS\*(C'\fR.  To get precisely the sections as
specified in the book, put the following in your \fI.perlcriticrc\fR
file:
.PP
.Vb 3
\&    [Documentation::RequirePodSections]
\&    source   = book_first_edition
\&    language = en_AU
.Ve
.PP
If you want to use
.PP
.Vb 3
\&    [Documentation::RequirePodSections]
\&    source   = module_starter_pbp
\&    language = en_US
.Ve
.PP
you will need to modify your \fI~/.module\-starter/PBP/Module.pm\fR
template because it is generated using Australian spelling.
.PP
Presently, the difference between \f(CW\*(C`en_AU\*(C'\fR and \f(CW\*(C`en_US\*(C'\fR is in how the
word \*(L"licence\*(R" is spelled.
.PP
The sections required for modules and programs can be independently
customized, overriding any values for \f(CW\*(C`source\*(C'\fR and \f(CW\*(C`language\*(C'\fR, by
giving values for \f(CW\*(C`script_sections\*(C'\fR and \f(CW\*(C`lib_sections\*(C'\fR of a string
of pipe-delimited required \s-1POD\s0 section names.  An example of entries
in a \fI.perlcriticrc\fR file:
.PP
.Vb 3
\&    [Documentation::RequirePodSections]
\&    lib_sections    = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR
\&    script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR
.Ve
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Currently, this Policy does not look for the required \s-1POD\s0 sections
below the \f(CW\*(C`=head1\*(C'\fR level.  Also, it does not require the sections to
appear in any particular order.
.PP
This Policy applies to the entire document, but can be disabled for a
particular document by a \f(CW\*(C`## no critic (RequirePodSections)\*(C'\fR annotation
anywhere between the beginning of the document and the first \s-1POD\s0 section
containing a \f(CW\*(C`=head1\*(C'\fR, the \f(CW\*(C`_\|_END_\|_\*(C'\fR (if any), or the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR (if any),
whichever comes first.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeffrey Ryan Thalhammer <jeff@imaginative\-software.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2006\-2011 Imaginative Software Systems.  All rights reserved.
.PP
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 \s-1LICENSE\s0 file included with this module