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

FreeBSD Manual Pages

  
 
  

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

NAME
       Perl::Critic::Policy::Documentation::RequirePodSections - Organize your
       POD into	the customary sections.

AFFILIATION
       This Policy is part of the core Perl::Critic distribution.

DESCRIPTION
       This Policy requires your POD to	contain	certain	"=head1" sections.  If
       the file	doesn't	contain	any POD	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.

DEFAULTS
       Different POD 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).

		       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

CONFIGURATION
       The default sections above are derived from Damian Conway's Perl	Best
       Practices 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: "source" and "language".

       The "source" option has two generic values, "book" and
       "module_starter_pbp", and two version-specific values,
       "book_first_edition" and	"module_starter_pbp_0_0_3".  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.

       The "language" option has a default, unnamed value but also accepts
       values of "en_AU" and "en_US".  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. "CONFIGURATION" instead of
       "CONFIGURATION AND ENVIRONMENT",	the removal of "VERSION", and the
       addition	of "EXIT STATUS".  To get precisely the	sections as specified
       in the book, put	the following in your .perlcriticrc file:

	   [Documentation::RequirePodSections]
	   source   = book_first_edition
	   language = en_AU

       If you want to use

	   [Documentation::RequirePodSections]
	   source   = module_starter_pbp
	   language = en_US

       you will	need to	modify your ~/.module-starter/PBP/Module.pm template
       because it is generated using Australian	spelling.

       Presently, the difference between "en_AU" and "en_US" is	in how the
       word "licence" is spelled.

       The sections required for modules and programs can be independently
       customized, overriding any values for "source" and "language", by
       giving values for "script_sections" and "lib_sections" of a string of
       pipe-delimited required POD section names.  An example of entries in a
       .perlcriticrc file:

	   [Documentation::RequirePodSections]
	   lib_sections	   = NAME | SYNOPSIS | BUGS AND	LIMITATIONS | AUTHOR
	   script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR

LIMITATIONS
       Currently, this Policy does not look for	the required POD sections
       below the "=head1" level.  Also,	it does	not require the	sections to
       appear in any particular	order.

       This Policy applies to the entire document, but can be disabled for a
       particular document by a	"## no critic (RequirePodSections)" annotation
       anywhere	between	the beginning of the document and the first POD
       section containing a "=head1", the "__END__" (if	any), or the
       "__DATA__" (if any), whichever comes first.

AUTHOR
       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT
       Copyright (c) 2006-2011 Imaginative Software Systems.  All rights
       reserved.

       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 LICENSE file included with this module

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

NAME | AFFILIATION | DESCRIPTION | DEFAULTS | CONFIGURATION | LIMITATIONS | AUTHOR | COPYRIGHT

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

home | help