Unix/Linux Go Back    


CentOS 7.0 - man page for perl::critic::policy::documentation::requirepodsections (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Perl::Critic::Policy::DocumentaUser:ConPerl::Critic::Policy::Documentation::RequirePodSections(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.16.3			       Perl::Critic::Policy::Documentation::RequirePodSections(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:55 AM.